Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updating the top level readme #45

Merged
merged 1 commit into from
Aug 11, 2024
Merged

Updating the top level readme #45

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 105 additions & 40 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# genweb

![status sheild](https://img.shields.io/static/v1?label=status&message=starting...&color=blue&style=plastic)
[![status sheild](https://img.shields.io/static/v1?label=released&message=none&color=active&style=plastic)](https://pypi.org/project/devopsdriver/0.1.45/)
[![GitHub](https://img.shields.io/github/license/marcpage/genweb?style=plastic)](https://github.com/marcpage/genweb?tab=Unlicense-1-ov-file#readme)
Expand All @@ -20,65 +22,128 @@
[![Python](https://img.shields.io/static/v1?label=&message=Pure%20Python&color=ffde57&style=plastic&logo=python)](https://python.org/)


# genweb
Generate a family history website



# Get source locally

- `git clone https://github.com/marcpage/genweb.git`


# Format source

On Linux:

- `./pr_build.py format`

or
## Description

Genweb is a tool that you can use to construct a website with your pictures in conjucntion with a geneology source (GEDCOM file).

- `python3 pr_build.py format`
## Concepts

When getting started there are a few pieces to put things together:
- **A GEDCOM file** this file can be exported from most geneology software
- **Collection of Artifacts** This is a folder that contains pictures, movies, and other files of interest
- **metadata.yml** This file describes the Artifacts and connects them with people (**TODO**: create a tool to edit this file)
- **TODO**: *(optional)* An AWS S3 and remote web server to share the site publicly and serve as a source-of-truth for maintainers of the site


# Validate source
## How to use

On Linux:
1. Export a GEDCOM file from you geneology software (tested with RootsMagic)
2. Collect all your artifacts into a folder
- These can be images, movides, and even mini-websites
3. Create `metadata.yml` in your artifacts folder
- This will describe the files and link people to them
4. *(optional)* Create `aliases.yml` in your artifacts folder
- People identifiers are generated by person name, birthyear, mother's name, mother's birthyear
- As family history research is conducted, the calculated identifiers can change
- This file maps old names to new names
5. Create file `genweb.yml`
6. Run `python3 -m genweb.genweb`

- `./pr_build.py`
## genweb.yml

or
`genweb.yml` should be created at the following location:

- `python3 pr_build.py`
- **Windows**: ???
- **Linux**: `~/.devopsdriver/genweb.yml`
- **macOS**: `~/Library/Preferences/genweb.yml`

It should contain the following contents:

```yaml
binaries_dir: path/to/artifacts/
metadata_yaml: /path/to/file.yml
gedcom_path: /path/to/file.ged
site_dir: path/to/output/
alias_path: /path/to/file.yml
```

# Setup
## %binaries_dir%

1. `python3 -m venv .venv`
1. Linux: `source .venv/bin/activate`
1. `pip3 install -r requirements.txt`
The `binaries_dir` is the directory that all your photos, videos, sub-websites reside.

**Note**: All pictures in this directory that are not part of a sub-website should have a filename unique in the directory (including all subdirectories).
This is usually accomplished by naming them `YYYYMMDDNNperson_identifier.ext`.
Where `YYYY` is the four-digit year, `MM` is the two-digit month, `DD` is the two-digit day, `NN` is a two-digit index, and `ext` is the file extension (like `.jpg`).


# Usage
## %metadata_yaml%

`pytest`
The format for the `metadata.yml` file is (**Note**: All artifact identifiers should start with the year):

`python3 -m genweb.artifact_editor <path to roots magic db>`
```yaml
year_picture_artifact_identifier:
type: picture
title: Title of the picture
file: picture_artifact_identifier.jpg
path: owning_person_identifier
width: 500 # or height: 500
people:
- person_identifier
- owning_person_identifier
year_inline_artifact_identifier:
type: inline
title: Title of the inline code
path: owning_person_identifier
contents: '<b>html</b> contents to insert into the page'
mod_date: '2015-05-26'
people:
- owning_person_identifier
- person_identifier
year_href_artifact_identifier:
type: href
title: Title of the sub-webpage
path: owning_person_identifier
folder: folder_name # %artifacts_dir%/owning_person_identifier/folder_name
file: start_page.html # %artifacts_dir%/owning_person_identifier/folder_name/start_page.html
mod_date: '2015-05-18'
people:
- owning_person_identifier
- person_identifier
```

`python3 -m genweb.build_web_pages <path to roots magic db> <web folder path> <admin email>`

## %gedcom_path%

This is the path to a GEDCOM 5.5 file.
The GEDCOM export from [RootsMagic](https://www.rootsmagic.com) has been tested and works.
This file is used to generate the relationships and define person-identifiers.

# Helpful git commands
### Person-identifiers

- **git pull** - Get latest changes from GitHub
- **git status** - Check for local changes
- **git add [file]** - Add a new file to local database
- **git mv [src] [dst]** - Move or rename local file
- **git rm [file]** - Delete file
- **git commit -a** - Put current changes into local database
- **git push** - Push changes in local database to GitHub
- **git checkout -b users/pagerk/[branch name]** - Creat local branch
Person-identifiers are of the format `LastFirstIYYYYLastFirstIYYYY` or `LastFirstIYYYY-`.
It consists of the last name, first name, middle initial (first middle name), and year of birth.
If the mother is known, the identifier has the person followed by the mother's name.
If the mother is not known, a hypher (-) suffix is used.

## %site_dir%

This is the directory that the website will be generated into.
This directory needs to be on the same disk (technically filesystem) as `%binaries_dir%`.
Instead of copying files from `%binaries_dir%` to `%site_dir%` they are linked, saving time and disk space.

## %alias_path%

Family information gets updated all the time.
For instance if someone's mother is discovered, the person-identifier for them may chance from `JonesThomasI2004-` to `JonesThomasI2004SmithSallyT1975`.
Since all the information in `%metadata_yaml%` is based on person-identifiers, you can account for changes like this without having to edit everything by using this file.
It will take the new person-identifier from the GEDCOM updates and translate them into the old identifier.

The format of the file is:
```yaml
oldest_person_id:
- old_person_id
- newest_person_id

oldest_person_id:
- newest_person_id
```
Loading