Add ord_schema API docs (#642)

* Add ord_schema API docs

* update years

* update templates dir

* install package during build

* remove stale developer sections

.readthedocs.yml

@@ -22,10 +22,16 @@ version: 2
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
-  fail_on_warning: true
+  fail_on_warning: false
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
 
-# Optionally set the version of Python and requirements required to build your docs
 python:
-  version: 3.7
   install:
-    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?= -W
+SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

docs/_templates/README

@@ -0,0 +1 @@
+Copied from /home/skearnes/miniconda3/lib/python3.9/site-packages/sphinx/templates/apidoc

docs/_templates/package.rst_t

@@ -0,0 +1,55 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [pkgname, "namespace"] | join(" ") | e | heading }}
+{% else %}
+{{- [pkgname] | join(" ") | e | heading }}
+{% endif %}
+
+{%- if is_namespace %}
+.. py:module:: {{ pkgname }}
+{% endif %}
+
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if subpackages %}
+Subpackages
+-----------
+
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}
+
+{%- if not modulefirst and not is_namespace %}
+Module contents
+---------------
+
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}

docs/build_docs.sh

@@ -28,6 +28,12 @@ set -ex
 #   --doc_out=. \
 #   ord-schema/proto/reaction.proto ord-schema/proto/dataset.proto
 
+# Generate RST for ord-schema.
+sphinx-apidoc -fTM -o ord_schema -t _templates ../ord_schema \
+  "../ord_schema/*_test.py" \
+  "../ord_schema/*/*_test.py" \
+  "../ord_schema/proto/" \
+  "../ord_schema/scripts/"
+
 # Run sphinx.
-pip install -Ur requirements.txt
 make clean html

docs/conf.py

@@ -13,12 +13,11 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
-from recommonmark import transform
 
 # -- Project information -----------------------------------------------------
 
 project = "Open Reaction Database"
-copyright = "2020 Open Reaction Database Project Authors"
+copyright = "2020–2022 Open Reaction Database Project Authors"
 author = "Open Reaction Database Project Authors"
 
 # -- General configuration ---------------------------------------------------
@@ -27,6 +26,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "sphinx.ext.napoleon",
     "sphinx_tabs.tabs",
 ]
 

docs/index.rst

@@ -61,7 +61,7 @@ underrepresented areas).
 
 .. toctree::
    :hidden:
-   :maxdepth: 2
-   :caption: Developers
+   :caption: API Documentation
+
+   ord_schema/ord_schema
 
-   developer/editor

docs/ord_schema/ord_schema.macros.rst

@@ -0,0 +1,24 @@
+ord\_schema.macros
+==================
+
+.. automodule:: ord_schema.macros
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+ord\_schema.macros.solutions
+----------------------------
+
+.. automodule:: ord_schema.macros.solutions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ord\_schema.macros.workups
+--------------------------
+
+.. automodule:: ord_schema.macros.workups
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/ord_schema/ord_schema.rst

@@ -0,0 +1,72 @@
+ord\_schema
+===========
+
+.. automodule:: ord_schema
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   ord_schema.macros
+
+
+ord\_schema.frozen\_message
+---------------------------
+
+.. automodule:: ord_schema.frozen_message
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ord\_schema.message\_helpers
+----------------------------
+
+.. automodule:: ord_schema.message_helpers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ord\_schema.resolvers
+---------------------
+
+.. automodule:: ord_schema.resolvers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ord\_schema.templating
+----------------------
+
+.. automodule:: ord_schema.templating
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ord\_schema.units
+-----------------
+
+.. automodule:: ord_schema.units
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ord\_schema.updates
+-------------------
+
+.. automodule:: ord_schema.updates
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ord\_schema.validations
+-----------------------
+
+.. automodule:: ord_schema.validations
+   :members:
+   :undoc-members:
+   :show-inheritance:

setup.py

@@ -56,6 +56,13 @@
         "xlwt>=1.3.0",
     ],
     extras_require={
+        "docs": [
+            "ipython>=7.18.1",
+            "Pygments>=2.7.2",
+            "sphinx>=3.3.1",
+            "sphinx-rtd-theme>=0.5.0",
+            "sphinx-tabs>=1.3.0",
+        ],
         "examples": [
             "glob2>=0.7",
             "matplotlib>=3.3.4",