Add readthedocs documentation support

[ggbecker]

Description:

• Add files to support hosting documentation on: https://readthedocs.org
• The developer_guide.adoc document has been broken into multiple files to enhance navigability
• Since readthedocs.org doesn't support adoc, it was needed to convert some stuff around to markdown.

A preview of how the documentation will look like can be seen in:

https://ggbecker-content.readthedocs.io/en/readthedocs-support/

Rationale:

• readthedocs.org will enable much faster navigation of documentation and will benefit a lot newcomers who want to find something about development of the project.
• No need to access github pages for documentation anymore.
• Better user experience.
• Automatic doc versioning according to new releases
• Deprecates https://github.com/ComplianceAsCode/content/blob/master/docs/manual/developer_guide.adoc

TODO List

- [ ] Port changes from: 1 (can be incorporated when it gets merged)

• Port changes from: 2
• Port changes from: 3
• Port changes from: 4
• Port changes from: 5
• Write Technical Documentation about the integration itself - how to build the documentation and dependencies
• Remove developer_guide.adoc references from project, mainly from CMakeLists.txt files
  - [ ] Migrate tests/README.md
  - [ ] Migrate docs/user_guide.adoc
  - [ ] Migrate example/README.md

Update1: Reduce the scope a bit so this can be merged and then other files can be migrated later.

[pep8speaks]

Hello @ggbecker! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

• In the file docs/conf.py:

Line 17:1: E402 module level import not at top of file
Line 32:5: E128 continuation line under-indented for visual indent
Line 33:5: E128 continuation line under-indented for visual indent
Line 34:5: E128 continuation line under-indented for visual indent
Line 35:5: E128 continuation line under-indented for visual indent
Line 36:5: E128 continuation line under-indented for visual indent
Line 37:1: E124 closing bracket does not match visual indentation

Comment last updated at 2020-11-09 16:31:49 UTC

[openscap-ci]

Changes identified:
Others:
 Changes in Python files.

Show details

Others:
 Python file docs/conf.py is newly added.
 Python file tests/init.py is newly added.
 Python file utils/init.py is newly added.

Recommended tests to execute:
 (cd build && cmake ../ && ctest -j4)

[jan-cerny]

It's amazing!

Suggestions:

• link it from README
• link it from the old page in case somebody has bookmarked the old page

Why are HTML tags used in the markdown docs?

[ggbecker]

It's amazing!

Suggestions:

* link it from README

* link it from the old page in case somebody has bookmarked the old page

Why are HTML tags used in the markdown docs?

Thank you for the suggestions. I'll update accordingly.

HTML tags were automatically generated when converting from AsciiDoc to MarkDown. We will have to manually port some of those tables. But for now we can keep it like since it still renders a nice table.

[ggbecker]

• README had developer guide links updated to use new location in readthedocs
• developer_guide.adoc has a deprecation note and the link to the new location.
• I have added support to Jinja Macros Documentation

[ggbecker]

The webhook to trigger builds on readthedocs is already in place, so pushes to master branch and new releases will automatically have the documentation generated

[ggbecker]

Python modules have been added to the documentation. You can preview the latest state here:

https://ggbecker-content.readthedocs.io/en/readthedocs-support/

[redhatrises]

Description:

• Add files to support hosting documentation on: https://readthedocs.org
• The developer_guide.adoc document has been broken into multiple files to enhance navigability
• Since readthedocs.org doesn't support adoc, it was needed to convert some stuff around to markdown.

A preview of how the documentation will look like can be seen in:

https://ggbecker-content.readthedocs.io/en/readthedocs-support/

Rationale:

• readthedocs.org will enable much faster navigation of documentation and will benefit a lot newcomers who want to find something about development of the project.
• No need to access github pages for documentation anymore.
• Better user experience.
• Automatic doc versioning according to new releases
• Deprecates https://github.com/ComplianceAsCode/content/blob/master/docs/manual/developer_guide.adoc

Is the developer guide readable without an internet connect in the repo itself? If not, that needs to be taken care of. Never assume access to an internet resource to read documentation.

[ggbecker]

Description:

• Add files to support hosting documentation on: https://readthedocs.org
• The developer_guide.adoc document has been broken into multiple files to enhance navigability
• Since readthedocs.org doesn't support adoc, it was needed to convert some stuff around to markdown.

A preview of how the documentation will look like can be seen in:
https://ggbecker-content.readthedocs.io/en/readthedocs-support/

Rationale:

• readthedocs.org will enable much faster navigation of documentation and will benefit a lot newcomers who want to find something about development of the project.
• No need to access github pages for documentation anymore.
• Better user experience.
• Automatic doc versioning according to new releases
• Deprecates https://github.com/ComplianceAsCode/content/blob/master/docs/manual/developer_guide.adoc

Is the developer guide readable without an internet connect in the repo itself? If not, that needs to be taken care of. Never assume access to an internet resource to read documentation.

The documentation still lives in the repo. They were just split and reside on a different directory: https://github.com/ggbecker/content/tree/readthedocs-support/docs/manual/developer

The documentation could be also built locally using sphinx tools and we can add as a target in the make command so users can have the same HTML files that readthedocs generate.

If we think about it, users that browse files locally, would also need to have a AsciiDoc processor to render the text, so we would be just changing the prerequisite.

[JAORMX]

Recently added docs for the ocp4 e2e tests #6319 any chance that could be included?

[ggbecker]

Recently added docs for the ocp4 e2e tests #6319 any chance that could be included?

Definitely. Thanks for the reminder.

[ggbecker]

• I have added a new custom CMake target docs that automatically builds the HTML documentation in case it detects the presence of certain python modules found on requirements.txt file.

• @JAORMX The documentation regarding e2e tests has been added. You can take a look in the preview doc: https://ggbecker-content.readthedocs.io/en/readthedocs-support/manual/developer/06_contributing_with_content.html#tests-ocp4

[jan-cerny]

It's amazing.

I appreciate the idea of adding the Python modules documentation.

In future I suggest reshuffling the sections and chapters a bit, because for example templates are hidden well.

[JAORMX]

/test e2e-aws-rhcos4-e8

test flake

[matejak]

Great, I see no objections, and the existing documentation has just been converted to Markdown, which means that it's prefectly usable offline.
So let's merge this before conflicts develop. Looking forward to follow-ups!