For Documentation Authors

We are learning about Sphinx and ReadTheDocs, and considering their use for creating documentation for the VIVO Ontology and related ontologies.

Documentation is produced using a hybrid of manual text production, manual figure production, and automated table of contents, table, term page, and index production.

Manual Text Production

The top page is index.rst which contains a preface, a table of contents, listy of tables, list of figures, and reference to the index, which is automatically generated by Sphinx.

Text is stored in pages with .rst file tpes. Pages are written using a text editor such as BBEdit, vim, or Sublime.

Documentation in a docs folder of the ontology GitHub repository, keeping ontology and documentation together.

Manual Figure Production

We use draw.io <http://draw.io>, also known as diagrams.net. This free to use, open source software is available for use through a browser or as a downloaded app.

Automated Text Production

One need is to provide search and index capability at the term level. A user should be able to find the documentation for date or person or disposition without difficulty.

A simple python script ontology-docs.py is included with the Organization Ontology. Given any ontology, the script can:

  1. Create pages for each term using python scripts – scripts would use annotation property values to automatically write pages of documentation from the ontology.

  2. Create tables of terms using queries of the ontology.

  3. Update lists of properties and classes as subsidiary tables of contents.

Automated GitHub pages

The documentation is automatically built and deployed on GitHub Pages using GitHub Actions. The scripts to do this were written by Michael Altfield and documented here: Continuous Documentation: Hosting Read the Docs on GitHub Pages (1/2)

Resulting Documentation Features

  1. No need for formatting examples – use “View Page Source” on any page to see how it was written

  2. No need to write about the tools. Each tool has outstanding documentation.

  3. See Sphinx to get started with the documentation.

  4. Use RestructuredText to write the documentation. RestructuredText is a mark-up language originally developed to document python.

  5. Use GitHub for collaboration, issue tracking, version control, and release management for the documentation. GitHub renders RestructuredText pages (pages with .rst file types) automatically for those who wish to check oor read pages directly from GitHub.

  6. Use Makefiles included with ReadTheDocs for rendering the documentation via HTML, PDF, or ePub.

  7. Automated generation of HTML, PDF, and ePub documentation formats, and hosting of the documentation in the Organization Ontology GitHub repository, using GitHub actions.