GeoSphere Documentation Website
Overview
This repository holds the source for the Geosphere documentation website. It is structured as a sphinx project and uses the python "sphinx" tool to generate the documentation as an HTML website.
This repository also holds a Dockerfile and defines a Helm chart for deploying the documentation as a hosted website.
Serving via Docker
If you only want to see the site as-is and serve it locally with little to no editing, you can build the docker image and run it by doing:
git clone git@gitlab.ssec.wisc.edu:cspp_geo/geosphere/geosphere-docs.git
cd geosphere-docs
docker build -t geosphere-docs:dev .
docker run -it --rm -p 8080:80 --name mygeosphere geosphere-docs:dev
And then open your browser to http://localhost:8080
. Note that the -it
in the
above docker run
command will make the execution interactive requiring Ctrl + C
to stop it. If you replace -it
with -d
then the docker container will run in the
background and will require docker kill mygeosphere
to stop it.
Contributing
If you would like to contribute changes to the documentation, it is recommended you make the changes locally first, generate the docs, and view them in a browser to make sure everything renders properly before making a merge request.
To do this you'll need to create a Python environment with the necessary dependencies
installed. The below commands can be run one time to download the latest version of
the documentation source and create a new conda-based environment for building the
documentation. Note that this assumes you have conda
(Anaconda, miniconda,
miniforge, or similar) already installed on your system.
git clone git@gitlab.ssec.wisc.edu:cspp_geo/geosphere/geosphere-docs.git
cd geosphere-docs
conda create -n geosphere-docs python=3.11
conda activate geosphere-docs
pip install -r requirements.txt
You will need to activate this environment (the conda activate
command) for
any new terminal session you start.
cd docs
make clean
make html
Then open _build/html/index.html
in your preferred browser (Mac open _build/html/index.html
).
Committing Changes
It is recommended that all changes to the site be made from a separate branch from main
so a merge request can be made and changes reviewed. This assumes that you have permissions
on this project's repository to create new branches. If you do not then you must
fork the
project and do your changes on a local copy of your fork's documentation.
To make a new branch from an already cloned repository:
git checkout -b my-new-branch
git push -u origin my-new-branch
where my-new-branch
is whatever descriptive name you want for the branch.
The above commands make the new branch locally and push it to SSEC Gitlab.
You can then make your changes to any of the files using a text editor, git add, git commit, and finally git push the files. For example, if you edited the "index.rst" file you would do:
git add docs/index.rst
git commit -m "Updated home page with funding sources"
git push
You can then go to the SSEC Gitlab project page and create a merge request for this new branch. A banner should appear to suggest this for you when you visit Gitlab after making a push.
Pulling in upstream changes
If you know that others have updated the documentation on the main
branch and you'd
like to include them in your local copy you can do the following. Note that this
assumes you have no uncommitted local changes.
git checkout main
git pull