Merge pull request #44 from lincc-frameworks/awo-fix-pre-commit

Author: drewoldag

.github/workflows/ci.yml

@@ -52,7 +52,7 @@ jobs:
     - name: Build docs
       run: |
         cd ../test/${{ matrix.foldername }}
-        sphinx-build -b html docs/source docs/build/html
+        sphinx-build -T -E -b html -d docs/build/doctrees ./docs docs/build/html
     - name: Tests
       run: |
         cd ../test/${{ matrix.foldername }}

python-project-template/.pre-commit-config.yaml

@@ -43,16 +43,19 @@ repos:
     rev: 5.12.0
     hooks:
       - id: isort
-        name: isort (python)
+        name: isort (python files in src/ and tests/)
         description: Sort and organize imports in .py files.
+        types: [python]
+        files: ^(src|tests)/
 
   - repo: local
     hooks:
       - id: pylint
-        name: pylint
+        name: pylint (python files in src/ and tests/)
         entry: pylint
         language: system
         types: [python]
+        files: ^(src|tests)/
         args:
           [
             "-rn", # Only display messages
@@ -66,10 +69,15 @@ repos:
         entry: sphinx-build
         language: system
         always_run: true
+        exclude_types: [file, symlink]
         args:
           [
+            "-T", # Show full trace back on exception
+            "-E", # Don't use saved env. always read all files.
             "-b", # Flag to select which builder to use
             "html", # Use the HTML builder
-            "docs/source", # Source directory of documents
+            "-d", # Flag for cached environment and doctrees
+            "docs/build/doctrees", # directory
+            "./docs", # Source directory of documents
             "docs/build/html", # Output directory for rendered documents.
           ]

python-project-template/.readthedocs.yml

@@ -17,4 +17,6 @@ sphinx:
 # Optionally declare the Python requirements required to build your docs
 python:
    install:
-   - requirements: docs/requirements.txt
+   - requirements: docs/requirements.txt
+   - method: pip
+     path: .

python-project-template/docs/Makefile

@@ -4,9 +4,12 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 
-import sys
 import os
+import sys
+
+import autoapi
 
+# Define path to the code to be documented **relative to where conf.py (this file) is kept**
 sys.path.insert(0, os.path.abspath('../src/'))
 
 # -- Project information -----------------------------------------------------
@@ -21,31 +24,29 @@ release = 'v0.1'
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.autosummary',
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode']
 
-templates_path = ['_templates']
+extensions.append('autoapi.extension')
+
+templates_path = []
 exclude_patterns = []
 
-master_doc = 'index'
-autodoc_member_order = "bysource"
-autosummary_generate = True  # Turn on sphinx.ext.autosummary
-autoclass_content = "both"  # Add __init__ doc (ie. params) to class summaries
+master_doc = 'index'  # This assumes that sphinx-build is called from the root directory
 html_show_sourcelink = False  # Remove 'view source code' from top of page (for html, not python)
-autodoc_inherit_docstrings = True  # If no docstring, inherit from base class
 add_module_names = False # Remove namespaces from class/method signatures
 
+autoapi_type = 'python'
+autoapi_dirs = ['../src']
+autoapi_add_toc_tree_entry = False
+autoapi_member_order = 'bysource'
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'alabaster'
-html_static_path = ['_static']
-
-html_sidebars = { '**': ['globaltoc.html', 'relations.html',  'searchbox.html'], }
+html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'searchbox.html'], }
 
 
 # Readthedocs theme

python-project-template/docs/source/conf.py.jinja renamed to python-project-template/docs/conf.py.jinja

@@ -4,10 +4,10 @@
    contain the root `toctree` directive.
 
 Welcome to {{module_name}}'s documentation!
-===================================
+========================================================================================
 
 .. toctree::
    :hidden:
 
    Home page <self>
-   API reference <_autosummary/{{module_name}}>
+   API Reference <autoapi/index>

python-project-template/docs/source/index.rst.jinja renamed to python-project-template/docs/index.rst.jinja

@@ -1,2 +1,3 @@
-sphinx==5.3.0
-sphinx_rtd_theme==1.1.1
+sphinx==6.1.3
+sphinx_rtd_theme==1.2.0
+sphinx-autoapi==2.0.1