oracle · nathanwn · Sep 1, 2023 · Aug 28, 2023 · Aug 28, 2023 · Aug 29, 2023
@@ -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

@@ -299,6 +299,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.

@@ -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
+```
@@ -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"]
 

@@ -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
@@ -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

@@ -0,0 +1,7 @@
+macaron.slsa\_analyzer.asset package
+====================================
+
+.. automodule:: macaron.slsa_analyzer.asset
+   :members:
+   :undoc-members:
+   :show-inheritance:
@@ -73,6 +73,14 @@ macaron.slsa\_analyzer.checks.provenance\_l3\_content\_check module
    :undoc-members:
    :show-inheritance:
 
+macaron.slsa\_analyzer.checks.provenance\_witness\_l1\_check module
+-------------------------------------------------------------------
+
+.. automodule:: macaron.slsa_analyzer.checks.provenance_witness_l1_check
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 macaron.slsa\_analyzer.checks.trusted\_builder\_l3\_check module
 ----------------------------------------------------------------
 

@@ -0,0 +1,26 @@
+macaron.slsa\_analyzer.package\_registry package
+================================================
+
+.. automodule:: macaron.slsa_analyzer.package_registry
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+macaron.slsa\_analyzer.package\_registry.jfrog\_maven\_registry module
+----------------------------------------------------------------------
+
+.. automodule:: macaron.slsa_analyzer.package_registry.jfrog_maven_registry
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+macaron.slsa\_analyzer.package\_registry.package\_registry module
+-----------------------------------------------------------------
+
+.. automodule:: macaron.slsa_analyzer.package_registry.package_registry
+   :members:
+   :undoc-members:
+   :show-inheritance:
@@ -0,0 +1,27 @@
+macaron.slsa\_analyzer.provenance.intoto package
+================================================
+
+.. automodule:: macaron.slsa_analyzer.provenance.intoto
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 1
+
+   macaron.slsa_analyzer.provenance.intoto.v01
+   macaron.slsa_analyzer.provenance.intoto.v1
+
+Submodules
+----------
+
+macaron.slsa\_analyzer.provenance.intoto.errors module
+------------------------------------------------------
+
+.. automodule:: macaron.slsa_analyzer.provenance.intoto.errors
+   :members:
+   :undoc-members:
+   :show-inheritance:
@@ -0,0 +1,7 @@
+macaron.slsa\_analyzer.provenance.intoto.v01 package
+====================================================
+
+.. automodule:: macaron.slsa_analyzer.provenance.intoto.v01
+   :members:
+   :undoc-members:
+   :show-inheritance:
@@ -0,0 +1,7 @@
+macaron.slsa\_analyzer.provenance.intoto.v1 package
+===================================================
+
+.. automodule:: macaron.slsa_analyzer.provenance.intoto.v1
+   :members:
+   :undoc-members:
+   :show-inheritance:
@@ -13,6 +13,8 @@ Subpackages
    :maxdepth: 1
 
    macaron.slsa_analyzer.provenance.expectations
+   macaron.slsa_analyzer.provenance.intoto
+   macaron.slsa_analyzer.provenance.witness
 
 Submodules
 ----------
@@ -24,3 +26,11 @@ macaron.slsa\_analyzer.provenance.loader module
    :members:
    :undoc-members:
    :show-inheritance:
+
+macaron.slsa\_analyzer.provenance.provenance module
+---------------------------------------------------
+
+.. automodule:: macaron.slsa_analyzer.provenance.provenance
+   :members:
+   :undoc-members:
+   :show-inheritance:
@@ -0,0 +1,18 @@
+macaron.slsa\_analyzer.provenance.witness package
+=================================================
+
+.. automodule:: macaron.slsa_analyzer.provenance.witness
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+macaron.slsa\_analyzer.provenance.witness.attestor module
+---------------------------------------------------------
+
+.. automodule:: macaron.slsa_analyzer.provenance.witness.attestor
+   :members:
+   :undoc-members:
+   :show-inheritance:
@@ -12,10 +12,12 @@ Subpackages
 .. toctree::
    :maxdepth: 1
 
+   macaron.slsa_analyzer.asset
    macaron.slsa_analyzer.build_tool
    macaron.slsa_analyzer.checks
    macaron.slsa_analyzer.ci_service
    macaron.slsa_analyzer.git_service
+   macaron.slsa_analyzer.package_registry
    macaron.slsa_analyzer.provenance
    macaron.slsa_analyzer.specs
 

@@ -32,3 +32,11 @@ macaron.slsa\_analyzer.specs.inferred\_provenance module
    :members:
    :undoc-members:
    :show-inheritance:
+
+macaron.slsa\_analyzer.specs.package\_registry\_spec module
+-----------------------------------------------------------
+
+.. automodule:: macaron.slsa_analyzer.specs.package_registry_spec
+   :members:
+   :undoc-members:
+   :show-inheritance:
@@ -0,0 +1,18 @@
+.. Copyright (c) 2023 - 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/.
+
+=========================
+Macaron Developer's Guide
+=========================
+
+To get started with contributing to Macaron, see the `CONTRIBUTING <https://github.com/oracle/macaron/blob/main/CONTRIBUTING.md>`_ page.
+
+To follow the project's code style, see the :doc:`Macaron Style Guide </pages/developers_guide/style_guide>` page.
+
+For API reference, see the :doc:`API Reference </pages/developers_guide/apidoc/index>` page.
+
+.. toctree::
+   :maxdepth: 1
+
+   style_guide
+   apidoc/index