I don't personally feel the need to have 'make doc' at all, but its not a problem to have it.
In the commit message subject line you have 'create markefile' 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' Odd that this does not fit the spelling guidelines (Common Words) below. > +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 shell-session is probably what you want here. > + > + $ make doc We document tox as the way to run integration tests (doc/rtd/topics/tests.rst) and also unit tests (HACKING.rst) so it feels more consistent to document 'tox -e doc' here. Maybe there is some reason that you wanted 'make' ? > + > +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 Can you remove this from the comments doc/rtd/index.rst ? Just to avoid the duplication and inevitable divergence. > + > +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 I'm guessing that Josh didn't decide on this, but personally 'user-data' 'vendor-data' and 'meta-data' seem more consistent. > + > +.. 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