docs: resolve Sphinx warnings caused by API reference and add Macaron style guide (#440)

Closes #433.
Resolve Sphinx warnings caused by:
1. using the `__all__` variable in `__init__.py` files
2. naming two or more classes with the same name
3. using `numpydoc` style `Attribute` section in class docstring
Add a style guide page to Macaron documentation.

---------

Signed-off-by: Nathan Nguyen <[email protected]>

Author: nathanwn

CONTRIBUTING.md

@@ -27,6 +27,9 @@ git commit --signoff
 
 Finally, make sure to sign your commits using a GPG key. See the instructions [here](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) for more information. A green `verified` label will appear next to your commit on GitHub if it is successfully signed.
 
+### Style Guide
+
+See our [Macaron Style Guide](./docs/source/pages/developers_guide/style_guide.rst).
 
 ### Pull request process
 
@@ -135,9 +138,9 @@ Ideally, the GitHub token must have **read** permissions for the repositories th
 
 After generating a GitHub personal-access token, please store its value in an environment variable called ``GITHUB_TOKEN``. This environment variable will be read by Macaron for its **analyze** command.
 
-### Running checks and tests locally
+## Running checks and tests locally
 
-#### Git hooks
+### Git hooks
 
 Using the pre-commit tool and its `.pre-commit-config.yaml` configuration, a number of [pre-commit hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_committing_workflow_hooks) ensure that your code is formatted correctly.
 
@@ -156,7 +159,7 @@ make check
 runs _all_ installed git hooks over your code. For more control over the code checks, the Makefile also implements the `check-bandit`, `check-flake8`, `check-lint`, `check-mypy`, and `check-actionlint` goals.
 
 
-#### Testing
+### Testing
 
 This repository is set up to test either standalone or as a pre-push git hook. Tests are stored in the `tests/` folder, and you can run them manually like so:
 ```bash
@@ -172,9 +175,9 @@ make integration-test
 Note that integration tests can take a long time to complete. Also the repositories that we clone for these tests will be stored under `output/` directory. If you do not remove/move this directory and run the pre-commit tool you might get errors.
 
 
-#### Generating documentation
+## Generating documentation
 
-As mentioned above, all package code should make use of [Python docstrings](https://www.python.org/dev/peps/pep-0257/) in [reStructured text format](https://www.python.org/dev/peps/pep-0287/). Using these docstrings and the documentation template in the `docs/source/` folder, you can then generate proper documentation in different formats using the [Sphinx](https://github.com/sphinx-doc/sphinx/) tool:
+As mentioned above, all package code should make use of [Python docstrings](https://www.python.org/dev/peps/pep-0257/) in [reStructured text format](https://www.python.org/dev/peps/pep-0287/) following [numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html) (with some exceptions - see our [style guide](https://oracle.github.io/pages/developers_guide/style_guide.html#docstrings)). Using these docstrings and the documentation template in the `docs/source/` folder, you can then generate proper documentation in different formats using the [Sphinx](https://github.com/sphinx-doc/sphinx/) tool:
 
 ```bash
 make docs

Makefile

@@ -304,6 +304,15 @@ dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt:
 docs: docs-clean
 	$(MAKE) -C docs/ html
 
+# Generate API reference pages in the documentation using `sphinx-apidoc`.
+.PHONY: docs-api
+docs-api:
+	sphinx-apidoc --no-toc --module-first --force --maxdepth 1 --output-dir docs/source/pages/developers_guide/apidoc/ src/
+
+# Combine the two targets `docs-api` and `docs`:
+# First generate API reference pages, then build the HTML documentation.
+.PHONY: docs-full
+docs-full: docs-api docs
 
 # Build the Docker image. The image name and tag are read from IMAGE_NAME and RELEASE_TAG
 # environment variables, respectively. By default "test" is used as the image tag.

docs/README.md

@@ -16,13 +16,26 @@ This command will build and generate the documentation into `docs/_build/html`.
 python3 -m http.server -d docs/_build/html
 ```
 
-## Extend the API reference.
+## Extend the API reference
 
-If you add a new module, make sure that it is added to the API reference. The API reference is generated using the [sphinx-apidoc](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html) tool.
+We use the [sphinx-apidoc](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html) tool to generate API reference automatically from Python docstrings. See the [Docstring section in the Macaron Style Guide](https://oracle.github.io/pages/developers_guide/style_guide.html#docstrings) for how to write docstrings in Macaron.
+
+If you make a code change, make sure to regenerate the API reference by running (with the dev environment activated):
+
+```
+make docs-api
+```
+
+This command uses [sphinx-apidoc](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html) to generate the API reference RST files into `docs/source/pages/developers_guide/apidoc/`. Make sure to check in these API reference RST files to the repository.
+
+You can then rebuild the whole HTML documentation with:
 
-From within the root directory of Macaron, run (with the dev environment activated):
 ```
-sphinx-apidoc --no-toc --module-first --force --maxdepth 1 --output-dir docs/source/pages/apidoc/ src/
+make docs
 ```
 
-This command will  generate the API reference RST files into `docs/source/pages/apidoc/`. Make sure to check in the changed source files to the repository.
+In addition, instead of running `make docs-api` and `make docs` separately, you can combine the two commands by running:
+
+```
+make docs-full
+```

docs/source/conf.py

@@ -30,18 +30,21 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    "sphinx.ext.napoleon",
-    "sphinx.ext.autodoc",
-    "sphinx.ext.autosectionlabel",
-    "sphinx_autodoc_typehints",
-    "numpydoc",
-    "sphinx_tabs.tabs",
+    "sphinx.ext.napoleon",  # Support parsing numpydoc style docstrings
+    "sphinx.ext.autodoc",  # Support generating API reference from docstrings
+    "sphinx.ext.autosectionlabel",  # Support referencing sections using their titles
+    "sphinx.ext.intersphinx",  # Support referencing external APIs
+    "sphinx_autodoc_typehints",  # Resolve type annotations in docstrings
+    "numpydoc",  # Support numpydoc style docstrings
+    "sphinx_tabs.tabs",  # Support tabbed views in documentation
 ]
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth = 2
 autodoc_member_order = "bysource"
 numpydoc_show_class_members = False
 
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv"]
 

docs/source/index.rst

@@ -36,9 +36,9 @@ concrete rules that can be checked automatically. Macaron has a customizable che
 Getting started
 ---------------
 
-To start with Macaron, see our :doc:`Installation </pages/installation>` and :doc:`Using </pages/using>` pages.
+To start with Macaron, see the :doc:`Installation </pages/installation>` and :doc:`Using </pages/using>` pages.
 
-For all services and technologies that Macaron supports, see our :doc:`Supported Technologies </pages/supported_technologies/index>` page.
+For all services and technologies that Macaron supports, see the :doc:`Supported Technologies </pages/supported_technologies/index>` page.
 
 -------------------------
 Current checks in Macaron
@@ -106,4 +106,4 @@ intermediate representations as abstractions. Using such abstractions, Macaron i
    pages/output_files
    pages/cli_usage/index
    pages/supported_technologies/index
-   pages/apidoc/index
+   pages/developers_guide/index

docs/source/pages/apidoc/index.rst renamed to docs/source/pages/developers_guide/apidoc/index.rst

@@ -1,9 +1,9 @@
 .. Copyright (c) 2022 - 2023, Oracle and/or its affiliates. All rights reserved.
 .. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
-===================
-Developer Reference
-===================
+=====================
+Macaron API Reference
+=====================
 
 .. toctree::
    :maxdepth: 1