1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
|
.. _docs:
Contribute to our docs
**********************
.. toctree::
:maxdepth: 1
:hidden:
Style guide <style_docs.rst>
Directory layout <docs_layout.rst>
The documentation for cloud-init is hosted in the
`cloud-init GitHub repository`_ and rendered on `Read the Docs`_. It is mostly
written in reStructuredText.
The process for contributing to the docs is largely the same as for code,
except that for cosmetic changes to the documentation (spelling, grammar, etc)
you can also use the GitHub web interface to submit changes as quick PRs.
Previewing the docs
===================
The documentation for submitted/active PRs is automatically built by Read the
Docs and served from the PR's "conversation" tab as an automatic check.
However, while you are working on docs for a feature you are adding, you will
most likely want to build the docs locally. There is a Makefile target to build
the documentation for you:
.. code-block:: shell-session
$ tox -e doc
This will do two things:
- Build the documentation using Sphinx.
- Run doc8 against the documentation source code.
Once built, the HTML files will be viewable in `doc/rtd_html`. Use your
web browser to open `index.html` to view and navigate the site.
How are the docs structured?
============================
We use `Diataxis`_ to organize our documentation. There is more detail on the
layout of the ``doc`` directory in the :doc:`docs_layout` article.
We also have a :doc:`style_docs` that will help you if you need to edit or
write any content.
In your first PR
=================
If you need some help with your contribution, you can contact us on our
`Matrix room <Matrix_>`_. If you have already submitted a
work-in-progress PR, you can also ask for guidance from our technical author
by `tagging s-makin`_ as a reviewer.
.. LINKS
.. include:: ../links.txt
.. _cloud-init GitHub repository: https://github.com/canonical/cloud-init/tree/main/doc/rtd
.. _Read the Docs: https://readthedocs.com/
.. _tagging s-makin: https://github.com/s-makin
|
