Add doc generated from code and docstrings

GitHub: fix mxcube#804

.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,34 @@
 }
 
 
+# -- Options for sphinx.ext.autodoc ------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+
+extensions.append("sphinx.ext.autodoc")
+
+autodoc_default_options = {
+    'members': 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),
+}
+
+
 # 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