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:

#. Create pages for each term using python scripts -- scripts would use annotation
   property values to automatically write pages of documentation from the ontology.
   
#. Create tables of terms using queries of the ontology.
   
#. 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) <https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/>`_

Resulting Documentation Features
--------------------------------
   
#. No need for formatting examples -- use "View Page Source" on any page to see how it 
   was written
   
#. No need to write about the tools.  Each tool has outstanding documentation.

#. See 
   `Sphinx 
   <https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html>`_ 
   to get
   started with the documentation.

#. Use `RestructuredText 
   <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`_ to 
   write the documentation.  RestructuredText is a mark-up language originally developed 
   to document python.
   
#. 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.
   
#. Use Makefiles included with `ReadTheDocs 
   <https://docs.readthedocs.io/en/stable/index.html>`_ for rendering
   the documentation via HTML, PDF, or ePub.
   
#. Automated generation of HTML, PDF, and ePub documentation formats, and hosting of
   the documentation in the Organization Ontology GitHub repository, using GitHub
   actions.