Writing documentation


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:

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.


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.