Writing documentation#

Note

For details please refer to Writing documentation.

Getting started#

Install documentation into a Python virtual environment#

Create a Python virtual environment (virtualenv) to install documentation into, and activate it:

sudo apt install python3-dev python3-pip python3-venv git
python3 -m venv pyenv
. pyenv/bin/activate
pip install wheel
pip install -e 'git+https://github.com/depositar/ckan.git#egg=ckan[requirements]'
pip install -e 'git+https://github.com/depositar/ckanext-data-depositario.git#egg=ckanext-data-depositario'
pip install -r pyenv/src/ckanext-data-depositario/requirements-docs.txt

Edit the reStructuredText files#

depositar’s documentation is created using Sphinx. To make changes to the documentation, use a text editor to edit the .rst files in pyenv/src/ckanext-data-depositario/doc. Some useful links to bookmark:

Sphinx’s reStructuredText Primer
reStructuredText cheat sheet
reStructuredText quick reference
Sphinx Markup Constructs is a full list of the markup that Sphinx adds on top of Docutils.

Build the docs#

You should now be able to build the CKAN documentation locally. Make sure your virtual environment is activated, and then run the these commands:

cd pyenv/src/ckanext-data-depositario
python setup.py build_sphinx

Now you can open the built HTML files in build/sphinx/html.

Important

When you build the docs, Sphinx prints out warnings about any broken cross-references, syntax errors, etc. We aim not to have any of these warnings, so when adding to or editing the docs make sure your changes don’t introduce any new ones.

It’s best to delete the build directory and completely rebuild the docs, to check for any warnings:

rm -rf build; python setup.py build_sphinx

Publish the docs#

depositar’s documentation is published using ReadTheDocs. ReadTheDocs will detect each change to the ckanext-data-depositario repository and build a new version.