Sphinx apidocs #10928

sarnold · 2023-07-29T18:30:27Z

Description:

adds highlighted source/links to module references in sphinx docs
also adds separate ssg API module view for comparison
- more hierarchical/compact, 100% generated from conf.py and index.rst

Rationale:

who doesn't want colored source code links in the API docs?
apidoc module is optional and independent of adding source code links

Review Hints:

download/view the workflow artifact
browse the Module References
note the config changes are minimal and the api/ dir is always generated

openshift-ci · 2023-07-29T18:30:37Z

Hi @sarnold. Thanks for your PR.

I'm waiting for a ComplianceAsCode member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

github-actions · 2023-07-29T18:32:04Z

Start a new ephemeral environment with changes proposed in this pull request:

Fedora Environment

Oracle Linux 8 Environment

Mab879

Thanks for this PR! I would be more comfortable if we split the docs changes from the tox changes.

I also left some comments on minor issues I saw.

Mab879 · 2023-07-31T13:42:34Z

README_dev_workflows.md

+
+Note the primary tox commands given above are order-dependent, eg:
+
+    $ git clone https://github.com/VCTLabs/scap-security-guide


Suggested change

$ git clone https://github.com/VCTLabs/scap-security-guide

$ git clone https://github.com/ComplianceAsCode/content

Oops! Fixed.

Mab879 · 2023-08-21T16:45:31Z

.github/workflows/gh-pages.yaml

@@ -53,7 +54,7 @@ jobs:
          git-config-email: openscap-ci@gmail.com
      - name: Upload artifact if the event is pull request
        uses: actions/upload-artifact@v3
-        if: ${{ github.event_name == 'pull_request' }}
+        #if: ${{ github.event_name == 'pull_request' }}


If plan on removing please just remove the line vs comment it.

Actually I just wanted to check artifacts in my fork, so that is now restored.

Mab879 · 2023-08-21T16:46:43Z

README_dev_workflows.md

@@ -0,0 +1,44 @@
+# Local SCAP workflows w/o distro packages


I would rather have this under docs/manual/developer.

Mab879 · 2023-08-21T18:08:25Z

tox.ini

+    -r requirements.txt
+
+commands =
+    #stubgen -m munch --export-less -o {toxinidir}


If this command is not used please remove it.

matejak · 2023-08-31T14:36:07Z

Thank you for the pull request, please don't be shy to share with us how you interact with the project, and what are the reasons behind it, because it looks like that you have built a layer of additional tooling around it in your environment.
Anyway, this PR seems to do many things at once - the summary mentions apidocs, but there are more items introduced - tox and also repolite, that are not related to apidocs documentation of this project.
Therefore, if you would like to get the tox content through as well, please split it into another PR, and as the associated configuration is quite extensive, we will need justification/documentation to be able to review the PR and to maintain the setup in the long term.
Related to that, we keep the build of the content compatible with Python 2.7 for at least one more year, and then, we will be stuck with Python 3.6 for a couple of more years, as this is the Python supported in the RHEL 8 and derived products, so I would suggest to reflect this in the tox setup as well. Of course, if the other parts of the community will require even more conservative approach, we will probably take that into the account as well.

sarnold · 2023-09-01T03:09:53Z

Thanks for the feedback; this PR is now limited to just the Sphinx docs with a very minimal tox file and updated (docs) requirements. The actual sphinx link check command is currently commented out to make it easier to see the docs build messages in a console.

Mab879

Thanks for making those changes, I just have a couple of comments.

tox.ini

* this adds highlighted source/links to module references in sphinx docs, plus a small tox file for sphinx builds and static linting Signed-off-by: Stephen L Arnold <sarnold@vctlabs.com>

Mab879

Thanks working on this PR. I do like the API docs. I have a few items of feedback:

Can you please add docs for installing tox in https://github.com/ComplianceAsCode/content/blob/master/docs/manual/developer/02_building_complianceascode.md?
I think the linkchecker might be useful it seems our existing checker isn't working on docs.

sarnold · 2023-09-20T22:44:39Z

1. Can you please add docs for installing tox in https://github.com/ComplianceAsCode/content/blob/master/docs/manual/developer/02_building_complianceascode.md?

Okay, the "best" place I could find looks like Sphinx packages unless you have another place in mind

2. I think the linkchecker might be useful it seems our existing checker isn't working on docs.

The sphinx link checker is running in commands_post so it will run regardless of the commands outcome.

* changes are in 02_building_complianceascode.md Signed-off-by: Stephen L Arnold <sarnold@vctlabs.com>

codeclimate · 2023-09-21T15:22:29Z

Code Climate has analyzed commit e275d0d and detected 0 issues on this pull request.

The test coverage on the diff in this pull request is 100.0% (50% is the threshold).

This pull request will bring the total coverage in the repository to 56.8% (3.0% change).

View more on Code Climate.

Mab879

Thank for your work on this!

openshift-ci bot added the needs-ok-to-test Used by openshift-ci bot. label Jul 29, 2023

sarnold force-pushed the sphinx-apidocs branch from e76e071 to f2a78e5 Compare July 29, 2023 19:49

Mab879 self-assigned this Aug 21, 2023

Mab879 reviewed Aug 24, 2023

View reviewed changes

sarnold force-pushed the sphinx-apidocs branch from f2a78e5 to 44825bd Compare September 1, 2023 03:00

Mab879 added this to the 0.1.70 milestone Sep 6, 2023

Mab879 added the Documentation Update in project documentation. label Sep 6, 2023

Mab879 requested changes Sep 7, 2023

View reviewed changes

tox.ini Outdated Show resolved Hide resolved

tox.ini Outdated Show resolved Hide resolved

sarnold force-pushed the sphinx-apidocs branch from 44825bd to 7fa9fbe Compare September 8, 2023 20:26

add sphinxcontrib-apidoc to docs build, test sphinx with tox file

03948b7

* this adds highlighted source/links to module references in sphinx docs, plus a small tox file for sphinx builds and static linting Signed-off-by: Stephen L Arnold <sarnold@vctlabs.com>

sarnold force-pushed the sphinx-apidocs branch from 7fa9fbe to 03948b7 Compare September 8, 2023 23:49

Mab879 requested changes Sep 13, 2023

View reviewed changes

Update developer page with tox method for building sphinx docs

e275d0d

* changes are in 02_building_complianceascode.md Signed-off-by: Stephen L Arnold <sarnold@vctlabs.com>

Mab879 approved these changes Sep 22, 2023

View reviewed changes

Mab879 added this pull request to the merge queue Sep 22, 2023

Mab879 removed this pull request from the merge queue due to the queue being cleared Sep 22, 2023

Mab879 merged commit 85221e4 into ComplianceAsCode:master Sep 22, 2023
37 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sphinx apidocs #10928

Sphinx apidocs #10928

sarnold commented Jul 29, 2023 •

edited

openshift-ci bot commented Jul 29, 2023

github-actions bot commented Jul 29, 2023

Mab879 left a comment

Mab879 Jul 31, 2023

sarnold Sep 1, 2023

Mab879 Aug 21, 2023

sarnold Sep 1, 2023

Mab879 Aug 21, 2023

Mab879 Aug 21, 2023

matejak commented Aug 31, 2023

sarnold commented Sep 1, 2023

Mab879 left a comment

Mab879 left a comment

sarnold commented Sep 20, 2023

codeclimate bot commented Sep 21, 2023

Mab879 left a comment


		Note the primary tox commands given above are order-dependent, eg:

		$ git clone https://github.com/VCTLabs/scap-security-guide

	$ git clone https://github.com/VCTLabs/scap-security-guide
	$ git clone https://github.com/ComplianceAsCode/content

Sphinx apidocs #10928

Sphinx apidocs #10928

Conversation

sarnold commented Jul 29, 2023 • edited

Description:

Rationale:

Review Hints:

openshift-ci bot commented Jul 29, 2023

github-actions bot commented Jul 29, 2023

Mab879 left a comment

Choose a reason for hiding this comment

Mab879 Jul 31, 2023

Choose a reason for hiding this comment

sarnold Sep 1, 2023

Choose a reason for hiding this comment

Mab879 Aug 21, 2023

Choose a reason for hiding this comment

sarnold Sep 1, 2023

Choose a reason for hiding this comment

Mab879 Aug 21, 2023

Choose a reason for hiding this comment

Mab879 Aug 21, 2023

Choose a reason for hiding this comment

matejak commented Aug 31, 2023

sarnold commented Sep 1, 2023

Mab879 left a comment

Choose a reason for hiding this comment

Mab879 left a comment

Choose a reason for hiding this comment

sarnold commented Sep 20, 2023

codeclimate bot commented Sep 21, 2023

Mab879 left a comment

Choose a reason for hiding this comment

sarnold commented Jul 29, 2023 •

edited