How to Contribute Documentation

Documentation is stored in doc/src/sphinx.

Dependencies are stored in doc/src/sphinx/requirements.txt.

conda

Create a virtual environment for documentation:

conda create -n clowder_docs python=3.8 -y
conda activate clowder_docs

Now we must edit the requirements.txt file to be compatible with Conda. These packages are not available on conda-forge.

Comment out the top three lines like so:

# -i https://pypi.org/simple/
# sphinx-rtd-theme==0.5.0
# sphinx_design==0.0.13
...

Install the dependencies. It’s always better to run all conda commands before installing pip packages.

conda install --file requirements.txt -y
pip install sphinx-rtd-theme==0.5.0 sphinx_design==0.0.13

pyenv

Create a virtual environment for documentation:

pyenv install 3.7.12 # or any 3.{7,8,9}
pyenv virtualenv 3.7.12 clowder_docs

# make virtual environemnt auto-activate
cd doc/src/sphinx
pyenv local clowder_docs

Install doc dependencies:

pip install -r requirements.txt

Now, build HTML docs for viewing:

# run from doc/src/sphinx
sphinx-autobuild . _build/html

Open http://127.0.0.1:8000 in your browser. Saved changes will be auto-updated in the browser.

(Optional alternative) Static builds

If you do not want dynamic builds, you can statically generate the HTML this way.

cd doc/src/sphinx
make html

View docs by opening index.html in the browser clowder/doc/src/sphinx/_build/html/index.html

⭐ If you experience any trouble, come ask us on Slack here! ⭐

Note

To see how to install Clowder, please see Installing Clowder.