Developer’s Guide¶

Start by forking the main repository: https://github.com/weecology/MillionTrees.
Clone your fork of the repository:
- Using HTTPS: git clone https://github.com/myUserName/MillionTrees.git
- Using SSH: git clone git@github.com:myUserName/MillionTrees.git
Link your cloned repository to the main repository (typically named upstream):
- git remote add upstream https://github.com/weecology/MillionTrees.git

Verify your remote settings with:

git remote -v

You should see output similar to:

origin    git@github.com:myUserName/MillionTrees.git (fetch)
origin    git@github.com:myUserName/MillionTrees.git (push)
upstream  https://github.com/weecology/MillionTrees.git (fetch)
upstream  https://github.com/weecology/MillionTrees.git (push)

Install the package from the main directory:

pip install . -U
# Or, if using uv for development:
# uv sync --dev extra

Documentation¶

We use Sphinx and Read the Docs for our documentation. Sphinx supports both reStructuredText and markdown as markup languages.

Source code documentation is automatically included after committing to the main repository. To add additional supporting documentation, create new reStructuredText or markdown files in the docs folder.

If you need to reorganize the documentation, refer to the Sphinx documentation.

Update Documentation¶

The documentation is automatically updated for changes within modules. However, it is essential to update the documentation after adding new modules in the milliontrees/ package.

Navigate to the docs directory and create a temporary directory, e.g., source.
Run the following command to generate documentation:
```
cd docs
mkdir source
sphinx-apidoc -f -o ./source ../src/milliontrees/
```
In this example, source is the destination folder for the generated .rst files, and ../src/milliontrees/ is the relative path to the milliontrees source code.
Review the generated files, make necessary edits to ensure accuracy, and then commit and push the changes.