Diff comments:
> diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py > index 4174477..9b27484 100644 > --- a/doc/rtd/conf.py > +++ b/doc/rtd/conf.py > @@ -17,7 +17,8 @@ from cloudinit.config.schema import get_schema_doc > # ] > > # General information about the project. > -project = 'Cloud-Init' > +project = 'cloud-init' More I was confused by the 'I' than the 'C'. I dont know what you intended in Common Words: A.) Cloud-init is awesome or B.) Cloud-Init is awesome. I had assumed it was 'A', but then you did 'B' here. > +copyright = '2019, Canonical Ltd.' > > # -- General configuration > ---------------------------------------------------- > > diff --git a/doc/rtd/topics/docs.rst b/doc/rtd/topics/docs.rst > new file mode 100644 > index 0000000..af2a3fb > --- /dev/null > +++ b/doc/rtd/topics/docs.rst > @@ -0,0 +1,83 @@ > +.. _docs: > + > +Docs > +**** > + > +These docs are hosted on Read the Docs. The following will explain how to > +contribute to and build these docs locally. > + > +The documentation is primarily written in reStructuredText. > + > + > +Building > +======== > + > +There is a makefile target to build the documentation for you: > + > +.. code-block:: shell > + > + $ make doc > + > +This will do two things: > + > +- Build the documentation using sphinx > +- Run doc8 against the documentation source code > + > +Once build the HTML files will be viewable in ``doc/rtd_html``. Use your > +web browser to open ``index.html`` to view and navigate the site. > + > +Style Guide > +=========== > + > +Headings > +-------- > +The headings used across the documentation use the following hierarchy: > + > +- ``*****``: used once atop of a new page > +- ``=====``: each sections on the page > +- ``-----``: subsections > +- ``^^^^^``: sub-subsections > +- ``"""""``: paragraphs > + > +The top level header ``######`` is reserved for the first page. > + > +If under and overline are used, their length must be identical. The length of > +the underline must be at least as long as the title itself > + > +Line Length > +----------- > +Please keep the line lengths to a maximum of **79** characters. This ensures > +that the pages and tables do not get too wide that side scrolling is > required. > + > +Header > +------ > +Adding a link at the top of the page allows for the page to be referenced by > +other pages. For example for the FAQ page this would be: > + > +.. code-block:: rst > + > + .. _faq: > + > +Footer > +------ > +The footer should include the textwidth > + > +.. code-block:: rst > + > + .. vi: textwidth=80 > + > +Vertical Whitespace > +------------------- > +One newline between each section helps ensure readability of the > documentation > +source code. > + > +Common Words > +------------ > +There are some common words that should follow specific usage: > + > +- ``cloud-init``: always lower case with a hyphen unless starting a sentence > +- ``metadata``: one word > +- ``user data``: two words, not to be combined > +- ``vendor data``: like user data, it is two words It just makes 'metadata' seem like an odd ball to me (should that be 'odd-ball' ? or 'oddball'. not sure. 😉). But oh well. > + > +.. vi: textwidth=80 -- https://code.launchpad.net/~powersj/cloud-init/+git/cloud-init/+merge/372102 Your team cloud-init commiters is requested to review the proposed merge of ~powersj/cloud-init:docs/config-tox into cloud-init:master. _______________________________________________ Mailing list: https://launchpad.net/~cloud-init-dev Post to : cloud-init-dev@lists.launchpad.net Unsubscribe : https://launchpad.net/~cloud-init-dev More help : https://help.launchpad.net/ListHelp