Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add prerequisites section for building documentation #1233

Merged

Conversation

javiertoledos
Copy link
Contributor

Missing prerequisites may hinder documentation contributions as it may throw errors when running make doc (specially the Python version) or when trying to validate spellcheck or linting.

Personally I found I had those tools missing when trying to compile the doc first time and Sphinx uses a python notation that is available since 3.8 but the error thrown is cryptic if python version is older.

@github-actions github-actions bot added the Documentation Documentation needs updating label Sep 20, 2024
@stgraber stgraber added the Incomplete Waiting on more information from reporter label Sep 20, 2024
@stgraber
Copy link
Member

Hello,

Before we can review this pull request, we need all the commits to include a suitable Signed-off-by line. You can see CONTRIBUTING.md for more information on that.

Thanks!

@javiertoledos javiertoledos force-pushed the doc/add-required-tools-for-building-doc branch from 2afb3f1 to efb7943 Compare September 21, 2024 00:49
@stgraber
Copy link
Member

.tmp/doc/contributing.md:80: MD004 Unordered list style
.tmp/doc/contributing.md:81: MD004 Unordered list style
.tmp/doc/contributing.md:82: MD004 Unordered list style
.tmp/doc/contributing.md:83: MD004 Unordered list style

Comment on lines 78 to 83
### Prerequisites

* Python 3.8+
* Python venv module
* Aspell (for spellchecking)
* Markdown lint tool (mdl)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You should use - here for the list so it matches the style of the others in this file.

Rather than add things like mdl and venv to the wordlist, it's best to just put them in a code block.

Given those requirements are specific to the documentation checking, it's probably best to move them into the Automatic documentation checks section.

So something like:

GitHub runs automatic checks on the documentation to verify the spelling, the validity of links, correct formatting of the Markdown files, and the use of inclusive language.

You can (and should!) run these tests locally as well with the following commands:
- Check the spelling: `make doc-spellcheck`
- Check the validity of links: `make doc-linkcheck`
- Check the Markdown formatting: `make doc-lint`
- Check for inclusive language: `make doc-woke`

To run the above, you will need the following:
- Python 3.8 or higher
- The `venv` python package
- The `aspell` tool for spellchecking
- The `mdl` markdown lint tool

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done, updated doc with comments above.

@javiertoledos javiertoledos force-pushed the doc/add-required-tools-for-building-doc branch from efb7943 to e2e78b9 Compare September 24, 2024 19:03
Signed-off-by: Javier Toledo <jtoledo@fastmail.com>
@stgraber stgraber force-pushed the doc/add-required-tools-for-building-doc branch from e2e78b9 to 14bc978 Compare September 24, 2024 20:24
@stgraber stgraber merged commit 87c628d into lxc:main Sep 24, 2024
30 checks passed
@stgraber
Copy link
Member

thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation Documentation needs updating Incomplete Waiting on more information from reporter
Development

Successfully merging this pull request may close these issues.

2 participants