From 5972a56f6d17a21f823c345e58bebce542830262 Mon Sep 17 00:00:00 2001 From: Steven Kearnes Date: Fri, 1 Jul 2022 10:44:16 -0400 Subject: [PATCH] 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 | 14 +++-- docs/Makefile | 2 +- docs/_templates/README | 1 + docs/_templates/package.rst_t | 55 ++++++++++++++++++ docs/build_docs.sh | 8 ++- docs/conf.py | 4 +- docs/developer/editor.rst | 82 --------------------------- docs/index.rst | 6 +- docs/ord_schema/ord_schema.macros.rst | 24 ++++++++ docs/ord_schema/ord_schema.rst | 72 +++++++++++++++++++++++ docs/requirements.txt | 6 -- setup.py | 7 +++ 12 files changed, 182 insertions(+), 99 deletions(-) create mode 100644 docs/_templates/README create mode 100644 docs/_templates/package.rst_t delete mode 100644 docs/developer/editor.rst create mode 100644 docs/ord_schema/ord_schema.macros.rst create mode 100644 docs/ord_schema/ord_schema.rst delete mode 100644 docs/requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml index e0a560161..6ae8bdd25 100644 --- a/.readthedocs.yml +++ b/.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 diff --git a/docs/Makefile b/docs/Makefile index b50c24dc3..d4bb2cbb9 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/_templates/README b/docs/_templates/README new file mode 100644 index 000000000..ed2caed5d --- /dev/null +++ b/docs/_templates/README @@ -0,0 +1 @@ +Copied from /home/skearnes/miniconda3/lib/python3.9/site-packages/sphinx/templates/apidoc diff --git a/docs/_templates/package.rst_t b/docs/_templates/package.rst_t new file mode 100644 index 000000000..678360e60 --- /dev/null +++ b/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 %} diff --git a/docs/build_docs.sh b/docs/build_docs.sh index 6d110fe12..71758d2e5 100755 --- a/docs/build_docs.sh +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 60e4ee07a..1039df9c7 100644 --- a/docs/conf.py +++ b/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", ] diff --git a/docs/developer/editor.rst b/docs/developer/editor.rst deleted file mode 100644 index 00157e517..000000000 --- a/docs/developer/editor.rst +++ /dev/null @@ -1,82 +0,0 @@ -################## -Interactive Editor -################## - -The ORD hosts an interactive web editor for ``Reaction`` and ``Dataset`` protos -on Google Cloud Platform (GCP); it is available at -`https://editor.open-reaction-database.org`. - -This document describes the setup and deployment process for GCP. - -*********************** -Update the docker image -*********************** - -If the editor code has changed, you will need to update the docker image on -Docker Hub (`link -`_). -Before starting, make sure that you have installed all of the required -`dependencies -`_. - -.. NOTE:: - This updates the ``latest`` tag for the ord-editor image. To set a different - tag add ":" to the end of the name; for example - ``openreactiondatabase/ord-editor:v0.0.0``. - -.. code-block:: shell - - $ cd "${ORD_SCHEMA_ROOT}/editor" - $ make package - $ docker build -t openreactiondatabase/ord-editor . - $ docker push openreactiondatabase/ord-editor - -************************ -Create a new VM instance -************************ - -.. NOTE:: - Only one instance at a time can access a persistent disk. If there is an - existing instance, make sure to (1) remove the instance from the instance - group and (2) shut down (and delete) the instance. - -1. In the `VM instances page `_, - click "Create instance" -2. Choose "New VM instance from template" from the side panel -3. Select ``ord-editor-template`` and click "Continue" - - * This template sets the container image as well as tags for firewall rules - and metadata for Cloud Logging - -4. Edit the new instance configuration: - - a. Choose a better name - b. Expand "Management, security, disks, networking, sole tenancy" - c. On the "Disks" tab, click "Attach existing disk" - - * Disk -> ``ord-editor-data`` - * Leave all other options at their default values - * Click "Done" - - d. Expand the "Advanced container options" - e. Under "Environment variables", add ``ORD_EDITOR_DB=/mnt/disks/ord-editor-data`` - f. Under "Volume mounts", add a new volume: - - * Volume Type -> Disk - * Mount path -> ``/mnt/disks/ord-editor-data`` - * Disk name -> ``ord-editor-data`` - * Mode -> Read/write - * Click "Done" - -5. Click "Create" to initialize the VM - -**************************** -Expose the editor to the web -**************************** - -#. Navigate to `Instance groups `_ - in the GCP console -#. Click on ``editor-instance-group`` -#. Click on "Edit Group" -#. Select the new instance under "Add an instance" -#. Click "Save" diff --git a/docs/index.rst b/docs/index.rst index df3cfe7b4..c40619012 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,7 +61,7 @@ underrepresented areas). .. toctree:: :hidden: - :maxdepth: 2 - :caption: Developers + :caption: API Documentation + + ord_schema/ord_schema - developer/editor diff --git a/docs/ord_schema/ord_schema.macros.rst b/docs/ord_schema/ord_schema.macros.rst new file mode 100644 index 000000000..d33182c12 --- /dev/null +++ b/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: diff --git a/docs/ord_schema/ord_schema.rst b/docs/ord_schema/ord_schema.rst new file mode 100644 index 000000000..6e4b203b2 --- /dev/null +++ b/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: diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index b9c3f1cad..000000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,6 +0,0 @@ -ipython>=7.18.1 -protobuf>=3.13.0 -Pygments>=2.7.2 -sphinx>=3.3.1 -sphinx-rtd-theme>=0.5.0 -sphinx-tabs>=1.3.0 diff --git a/setup.py b/setup.py index e6a2c971b..a4ab4ba47 100644 --- a/setup.py +++ b/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",