Fixes docs build, adds workflow to build docs.

Improves auto-generated source files and adds more information.
seantis · Aug 27, 2024 · 7bb79b3 · 7bb79b3
1 parent bbb930a
commit 7bb79b3
Show file tree

Hide file tree

Showing 16 changed files with 4,807 additions and 1,598 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,24 @@
+name: Docs
+
+on:
+  workflow_dispatch:  # allow to run manually
+  push:
+    branches: [master]
+
+jobs:
+  pages:
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    permissions:
+      pages: write
+      id-token: write
+
+    steps:
+    - id: deployment
+      uses: sphinx-notes/pages@v3
+      with:
+        python_version: '3.11'
diff --git a/docs/Makefile b/docs/Makefile
@@ -15,9 +15,9 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help
 help:

diff --git a/docs/source/_static/custom.css → docs/_static/custom.css b/docs/source/_static/custom.css → docs/_static/custom.css
diff --git a/docs/source/_static/logo.svg → docs/_static/logo.svg b/docs/source/_static/logo.svg → docs/_static/logo.svg
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,9 @@
+Suitable API Documentation
+==========================
+
+.. automodule:: suitable.api
+   :members: install_strategy_plugins
+
+   .. autoclass:: suitable.api.Api
+      :members:
+      :inherited-members:
diff --git a/docs/source/conf.py → docs/conf.py b/docs/source/conf.py → docs/conf.py
@@ -33,14 +33,16 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
 ]
+if sys.version_info >= (3, 11):
+    extensions += ['sphinxcontrib.autodoc_inherit_overload']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+#source_suffix = '.rst'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -49,25 +51,25 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'Suitable'
-copyright = u'2016, Denis Krienbühl'
-author = u'Denis Krienbühl'
+project = 'Suitable'
+copyright = '2016, Denis Krienbühl'
+author = 'Denis Krienbühl'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u'0.19.2'
+version = '0.19.2'
 # The full version, including alpha/beta/rc tags.
-release = u'0.19.2'
+release = '0.19.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -77,7 +79,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ['_build']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -211,7 +213,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'Suitable.tex', u'Suitable Documentation',
+    (master_doc, 'Suitable.tex', 'Suitable Documentation',
      u'Denis Krienbühl', 'manual'),
 ]
 
@@ -241,7 +243,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'suitable', u'Suitable Documentation',
+    (master_doc, 'suitable', 'Suitable Documentation',
      [author], 1)
 ]
 
@@ -255,7 +257,7 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'Suitable', u'Suitable Documentation',
+    (master_doc, 'Suitable', 'Suitable Documentation',
      author, 'Suitable', 'One line description of project.',
      'Miscellaneous'),
 ]
@@ -274,7 +276,7 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/3/', None)}
 
 # Document hidden methods as well.
 autoclass_content = 'both'
diff --git a/docs/source/index.rst → docs/index.rst b/docs/source/index.rst → docs/index.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1 +1,2 @@
-sphinx
+sphinx
+sphinxcontrib.autodoc-inherit-overload
diff --git a/docs/source/api.rst b/docs/source/api.rst
diff --git a/pyproject.toml b/pyproject.toml
@@ -22,6 +22,10 @@ explicit_package_bases = true
 strict = true
 mypy_path = "$MYPY_CONFIG_FILE_DIR/src"
 
+[[tool.mypy.overrides]]
+module = ["suitable._module_types"]
+warn_return_any = false
+
 [tool.tox]
 legacy_tox_ini = """
 [tox]