Skip to content
Snippets Groups Projects

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