datalad-tabby/docs

Editing, building, and publishing extension documentation

The datalad-extension-template uses Sphinx for document generation and suggests using Read the Docs for automatic documentation building, versioning, and hosting.

Once you are ready to document your extension software, take note of the following:

Document editing

Edit your docs/source/index.rst file using reStructuredText, which is the default plaintext markup language used by Sphinx. Add further documentation as needed.

Local testing

For testing locally whether your documentation builds and renders correctly, first install the developer requirements from the repository's root directory:

pip install -r requirements-devel.txt

Then build the documentation locally:

make -C docs html

Navigate to docs/build/ and open index.html in your browser to view your documentation.

Remote building and testing

The GitHub Action workflow located at .github/workflows/docbuild.yml will run on a push or pull request to your GitHub repository's master/main branch. This builds the documentation remotely and serves as an automated documentation test.

Publishing your documentation

• If you maintain your extension yourself outside of the scope of the DataLad GitHub organization, you can follow these instructions for integrating your version control system (such as GitHub) with Read the Docs.
• If your extension is maintained by the DataLad developer team, please create an issue asking for help with the setup.