New South Wales Forest Observatory¶
Scripts, notebooks, figures & docs for the New South Wales Forest Observatory expansion.
Documentation: docs.salo.ai/forestobs-nsw
Source code: salosciences/forestobs-nsw
Introduction¶
This is a repo to store one-off or in-progress workflows for generating datasets and figures for the expansion of the Forest Observatory into New South Wales.
Data storage¶
We've set up a dedicated GCS bucket for storing data:
gs://nsw-scratch/
Store and access geospatial/other big data here instead of tracking it with this repository.
Software environment¶
There's no central software environment we're setting up for everyone to use - each of us has separate workflows and dependencies, and it doesn't seem necessary to standardize across them.
But we have created two files that contain useful packages for accessing data from cloud storage or for creating documentation. The first is environment-dev.yml, which contains useful conda packages like jupyter and fsspec/gcsfs for cloud storage access. Run this from inside your environment:
mamba install --file environment-dev.yml -c conda-forge
There are some additional python packages for generating documentation. From inside your environment:
pip install -r requirements-dev.txt
Documenting your work¶
Documentation for most scripts is not required. If there are workflows that will be useful for others to know about, or decisions made during data processing, it would be helpful to document these.
There's a documentation system setup through mkdocs. You can write documentation via Markdown files, or you could even just directly render Jupyter Notebooks.
Run mkdocs serve to serve the documentation in your browser.
See the mkdocs.yml file in the base of this repository for the layout of the documentation tree.
Documenting jupyter notebooks¶
You can render Jupyter Notebooks in the docs page. I've found the easiest way to do that is to create a symbolic link from inside the docs/ directory to the notebooks/ directory from the base of the repository.
You can see an example of this in docs/notebooks/visualize_class_env_patterns.ipynb, which is just a symbolic link to notebooks/visualize_class_env_patterns.ipynb.
Unfortunately, you have to manually create a symbolic link and commit it to github for it to render. This is because mkdocs only renders files in the docs/ directory, though I think we could probably change this as a config option in mkdocs.yml. Just haven't thought hard about how.
Branching¶
Please commit your work on a separate branch and then merge it into main. It's easier to manage a bunch of merges than it is to have a bunch of people all committing to the same branch.