Add API doc using autosummary. (#23)

Document API by generating docs with autosummary for each module.

* README.md
* ROADMAP.md
* docs/sphinx/_static/css/api-docs.css
* docs/sphinx/_templates/custom-module-template.rst
* docs/sphinx/api/sphinx_polyversion.rst
* docs/sphinx/conf.py
* docs/sphinx/index.rst
* sphinx_polyversion/git.py : Fix docs.
* sphinx_polyversion/json.py : Fix docs.

Author: vpratz

README.md

@@ -233,6 +233,8 @@ that isn't merged in the end.
 
 By contributing you affirm the [Developer Certificate of Origin](https://developercertificate.org/) and license your work under the terms of this repository.
 
+New top-level modules must be added to `docs/sphinx/api/sphinx_polyversion.rst`.
+
 ## License
 
 MIT License <br>

ROADMAP.md

@@ -72,10 +72,11 @@
     - [ ] Updating docs from old versions using cherry-pick
   - [ ] Subclassing guide
   - [ ] Reference
+    - [ ] Further explanation accompanying the reference (for new contributors) and users who want to extend inside `poly.py`
     - [ ] Command line syntax
-    - [ ] API
-    - [ ] Abstract classes
-    - [ ] Implementations
+    - [x] API
+    - [x] Abstract classes
+    - [x] Implementations
 - [ ] Contributing Standards
   - [ ] Contributing
   - [ ] Workflows, Policies

docs/sphinx/_static/css/api-docs.css

@@ -0,0 +1,4 @@
+/* align tables left in API docs (default was center) */
+table.autosummary.longtable {
+    margin-left: 0;
+}

docs/sphinx/_templates/custom-module-template.rst

@@ -0,0 +1,62 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+    {% block attributes %}
+    {% if attributes %}
+    .. rubric:: Module Attributes
+
+    .. autosummary::
+    {% for item in attributes %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block functions %}
+    {% if functions %}
+    .. rubric:: {{ _('Functions') }}
+
+    .. autosummary::
+    {% for item in functions %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block classes %}
+    {% if classes %}
+    .. rubric:: {{ _('Classes') }}
+
+    .. autosummary::
+    {% for item in classes %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block exceptions %}
+    {% if exceptions %}
+    .. rubric:: {{ _('Exceptions') }}
+
+    .. autosummary::
+    {% for item in exceptions %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block modules %}
+    {% if modules %}
+    .. rubric:: Modules
+
+    .. autosummary::
+    :toctree:
+    :template: custom-module-template.rst
+    :recursive:
+    {% for item in modules %}
+    {{ item }}
+    {%- endfor %}
+
+    {% endif %}
+    {% endblock %}

docs/sphinx/api/sphinx_polyversion.rst

@@ -0,0 +1,22 @@
+.. currentmodule:: sphinx_polyversion
+
+Public API
+==========
+
+.. autosummary::
+    :toctree: .
+    :template: custom-module-template.rst
+    :recursive:
+
+    api
+    builder
+    driver
+    environment
+    git
+    json
+    log
+    main
+    pyvenv
+    sphinx
+    utils
+    vcs

docs/sphinx/conf.py

@@ -56,6 +56,13 @@
     "sphinx.ext.githubpages",
 ]
 
+autosummary_ignore_module_all = False
+autodoc_default_options = {
+    "members": True,
+    "show-inheritance": True,
+    "special-members": "__call__, __aenter__, __aexit__",
+}
+
 exclude_patterns = []
 
 myst_enable_extensions = [
@@ -92,6 +99,7 @@
     #
     # style the version selector
     "css/version-selector.css",
+    "css/api-docs.css",
 ]
 
 templates_path = [

docs/sphinx/index.rst

@@ -24,6 +24,8 @@ Table of Contents
     :maxdepth: 2
     :caption: Reference
 
+    api/sphinx_polyversion
+
 .. toctree::
     :maxdepth: 1
     :caption: Development

sphinx_polyversion/git.py

@@ -485,7 +485,7 @@ async def predicate(self, root: Path, ref: GitRef) -> bool:
         """
         Check whether a revision should be build.
 
-        This predicate is used by :method:`retrieve` to filter the
+        This predicate is used by :meth:`retrieve` to filter the
         git references retrieved.
 
         Parameters

sphinx_polyversion/json.py

@@ -74,7 +74,7 @@ def _from_json_fields(cls: Type[T], o: Any) -> T:
         ----------
         o : Any
             The deserialized fields as they were returned
-            by :method:`_json_fields` earlier.
+            by :meth:`_json_fields` earlier.
 
         Returns
         -------
@@ -262,7 +262,7 @@ def __call__(self, o: JSONable) -> JSON_TYPE_DUMP:
 
         Notes
         -----
-        Calls :method:`transform` internally.
+        Calls :meth:`transform` internally.
 
         """
         return self.transform(o)
@@ -285,7 +285,7 @@ class Decoder(json.JSONDecoder):
     protocol or a :class:`JSONHook` has to be implemented for the type.
     2. The object has to be encoded in the correct format as done by :class:`Encoder`.
     3. THe hook or class has to be registered with this decoder. You can use
-    :method:`register` for that. This method can also be used as a class decorator.
+    :meth:`register` for that. This method can also be used as a class decorator.
 
     Parameters
     ----------
@@ -505,7 +505,7 @@ def from_json(cls: str, o: JSON_TYPE) -> Any:  # noqa: PLW0211
         Instanciate an object from its fields.
 
         This method is only called with supported instances that were
-        encoded with the help of :method:`fields`.
+        encoded with the help of :meth:`fields`.
 
         Parameters
         ----------