Add doc generated from code and docstrings

GitHub: fix mxcube#804

.github/workflows/pages.yaml

@@ -9,6 +9,7 @@ concurrency:
 
 on:
   push:
+  pull_request:
 
 jobs:
 
@@ -35,7 +36,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install poetry --user
-          python -m poetry install
+          python -m poetry install --only=docs,main
 
       - name: "Build documentation with Sphinx"
         run: |

.readthedocs.yaml

@@ -6,21 +6,23 @@
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 
+# This uses custom commands, because we need to install dependencies
+# from both Conda and Poetry.
+
+
 version: 2
 
 build:
 
   os: "ubuntu-22.04"
 
   tools:
-    python: "3.8"
+    python: "mambaforge-22.9"
 
   commands:
-    - "asdf plugin add poetry"
-    - "asdf install poetry latest"
-    - "asdf global poetry latest"
-    - "poetry install --only docs"
-    - "poetry run sphinx-build -T -E -b html -c ./docs/ ./docs/source/ ${READTHEDOCS_OUTPUT}/html/"
+    - "mamba env create --file conda-environment-dev.yml"
+    - "mamba run --name mxcubecore poetry install --only=docs,main"
+    - "mamba run --name mxcubecore poetry run sphinx-build -T -E -b html -c ./docs/ ./docs/source/ ${READTHEDOCS_OUTPUT}/html/"
 
 
 ...  # EOF

conda-environment-dev.yml

@@ -3,12 +3,17 @@ channels:
   - conda-forge
 dependencies:
   - python >=3.8,<3.11
+  # Run-time
   - openldap
   - python-ldap=3.4.0
+  # Dev
   - pip
-  - pytest
-  - coverage
-  - flake8
+  - poetry
+  # Format, lint
   - black
+  - flake8
+  # Test
+  - coverage
+  - pytest
   - pytest-cov
   - pytest-mock

docs/conf.py

@@ -57,4 +57,56 @@
 }
 
 
+# -- Extensions --------------------------------------------------------------
+
+
+# -- Options for sphinx.ext.autodoc
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+
+extensions.append("sphinx.ext.autodoc")
+
+autodoc_default_options = {
+    "inherited-members": True,
+    "members": True,
+    "show-inheritance": True,
+}
+
+autodoc_typehints = "both"
+
+
+# -- Options for sphinx.ext.autosummary
+# https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html
+
+extensions.append("sphinx.ext.autosummary")
+
+autosummary_generate = True
+
+
+# -- Options for sphinx.ext.intersphinx
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
+
+extensions.append("sphinx.ext.intersphinx")
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+}
+
+
+# -- Options for sphinx.ext.napoleon
+# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
+
+# We use Google style docstrings
+# https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
+
+extensions.append("sphinx.ext.napoleon")
+
+napoleon_numpy_docstring = False
+
+
+# -- Options for sphinx.ext.viewcode
+# https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html
+
+extensions.append("sphinx.ext.viewcode")
+
+
 # EOF

docs/source/dev/api.rst

@@ -0,0 +1,15 @@
+..
+
+
+***
+API
+***
+
+.. autosummary::
+    :toctree: autosummary
+    :recursive:
+
+    mxcubecore
+
+
+..  EOF

docs/source/dev/autosummary/.gitignore

@@ -0,0 +1,7 @@
+#
+
+
+*
+
+
+# EOF