Thanks for the reviews.

Fixed the commit message and responded to comments below.

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'

Maybe it is my eye, but since it is not starting a sentence it looked weird for 
the 'C' to be capitalized on its own as a title.

> +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

It was shorter; I will switch that.

> +
> +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

Yeah I have another merge that does some reorganization, I can make that 
removal a part of this merge.

> +
> +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

yes thx

> +
> +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

Right, I took what we were told to use when writing the white paper and put it 
in here as I have found both throughout. My intention was to bring some 
consistency.

> +
> +.. 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

Reply via email to