Merge ~powersj/cloud-init:docs/config-tox into cloud-init:master

Proposed by Joshua Powers on 2019-08-30
Status: Merged
Approved by: Scott Moser on 2019-09-07
Approved revision: 7375eec73e00b622f149527afd93a812dac7be68
Merge reported by: Server Team CI bot
Merged at revision: not available
Proposed branch: ~powersj/cloud-init:docs/config-tox
Merge into: cloud-init:master
Diff against target: 175 lines (+97/-22)
5 files modified
Makefile (+3/-1)
doc/rtd/conf.py (+3/-10)
doc/rtd/index.rst (+0/-9)
doc/rtd/topics/docs.rst (+84/-0)
tox.ini (+7/-2)
Reviewer Review Type Date Requested Status
Scott Moser 2019-08-30 Approve on 2019-09-07
Server Team CI bot continuous-integration Approve on 2019-09-06
Review via email: mp+372102@code.launchpad.net

Commit message

doc: document doc, create makefile and tox target

* Create makefile and tox targets for documentation building and testing
to better replicate the live web docs using the same theme.
* Created docs.rst to explain how to build and contribute to documentation
with style guide and tips.
* doc/rtd/conf.py:
    * Add copyright to rtd config
    * Use Sphinx's RTD theme to replicate actual docs

To post a comment you must log in.

PASSED: Continuous integration, rev:3366a331a27d601159604fa1a4531167a45da623
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1102/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Unit & Style Tests
    SUCCESS: Ubuntu LTS: Build
    SUCCESS: Ubuntu LTS: Integration
    IN_PROGRESS: Declarative: Post Actions

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1102//rebuild

review: Approve (continuous-integration)
Scott Moser (smoser) wrote :

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'

Joshua Powers (powersj) wrote :

Thanks for the reviews.

Fixed the commit message and responded to comments below.

Scott Moser (smoser) :
~powersj/cloud-init:docs/config-tox updated on 2019-09-04
8a19f93... by Joshua Powers on 2019-09-04

fixes from review

PASSED: Continuous integration, rev:8a19f935dd5bc037ef74e1820b73c1a38b421450
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1104/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Unit & Style Tests
    SUCCESS: Ubuntu LTS: Build
    SUCCESS: Ubuntu LTS: Integration
    IN_PROGRESS: Declarative: Post Actions

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1104//rebuild

review: Approve (continuous-integration)
Scott Moser (smoser) :
~powersj/cloud-init:docs/config-tox updated on 2019-09-06
7375eec... by Joshua Powers on 2019-09-06

clarify capitalization of cloud-init

also fix textwidth to be in line with doc

PASSED: Continuous integration, rev:7375eec73e00b622f149527afd93a812dac7be68
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1105/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Unit & Style Tests
    SUCCESS: Ubuntu LTS: Build
    SUCCESS: Ubuntu LTS: Integration
    IN_PROGRESS: Declarative: Post Actions

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1105//rebuild

review: Approve (continuous-integration)
Scott Moser (smoser) :
review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1diff --git a/Makefile b/Makefile
2index 4ace227..2c6d0c8 100644
3--- a/Makefile
4+++ b/Makefile
5@@ -106,7 +106,9 @@ deb-src:
6 echo sudo apt-get install devscripts; exit 1; }
7 $(PYVER) ./packages/bddeb -S -d
8
9+doc:
10+ tox -e doc
11
12 .PHONY: test pyflakes pyflakes3 clean pep8 rpm srpm deb deb-src yaml
13 .PHONY: check_version pip-test-requirements pip-requirements clean_pyc
14-.PHONY: unittest unittest3 style-check
15+.PHONY: unittest unittest3 style-check doc
16diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py
17index 4174477..9b27484 100644
18--- a/doc/rtd/conf.py
19+++ b/doc/rtd/conf.py
20@@ -17,7 +17,8 @@ from cloudinit.config.schema import get_schema_doc
21 # ]
22
23 # General information about the project.
24-project = 'Cloud-Init'
25+project = 'cloud-init'
26+copyright = '2019, Canonical Ltd.'
27
28 # -- General configuration ----------------------------------------------------
29
30@@ -59,15 +60,7 @@ show_authors = False
31
32 # The theme to use for HTML and HTML Help pages. See the documentation for
33 # a list of builtin themes.
34-html_theme = 'default'
35-
36-# Theme options are theme-specific and customize the look and feel of a theme
37-# further. For a list of options available for each theme, see the
38-# documentation.
39-html_theme_options = {
40- "bodyfont": "Ubuntu, Arial, sans-serif",
41- "headfont": "Ubuntu, Arial, sans-serif"
42-}
43+html_theme = 'sphinx_rtd_theme'
44
45 # The name of an image file (relative to this directory) to place at the top
46 # of the sidebar.
47diff --git a/doc/rtd/index.rst b/doc/rtd/index.rst
48index 20a99a3..c670b20 100644
49--- a/doc/rtd/index.rst
50+++ b/doc/rtd/index.rst
51@@ -1,14 +1,5 @@
52 .. _index:
53
54-.. http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
55-.. As suggested at link above for headings use:
56-.. # with overline, for parts
57-.. * with overline, for chapters
58-.. =, for sections
59-.. -, for subsections
60-.. ^, for subsubsections
61-.. “, for paragraphs
62-
63 #############
64 Documentation
65 #############
66diff --git a/doc/rtd/topics/docs.rst b/doc/rtd/topics/docs.rst
67new file mode 100644
68index 0000000..1b15377
69--- /dev/null
70+++ b/doc/rtd/topics/docs.rst
71@@ -0,0 +1,84 @@
72+.. _docs:
73+
74+Docs
75+****
76+
77+These docs are hosted on Read the Docs. The following will explain how to
78+contribute to and build these docs locally.
79+
80+The documentation is primarily written in reStructuredText.
81+
82+
83+Building
84+========
85+
86+There is a makefile target to build the documentation for you:
87+
88+.. code-block:: shell-session
89+
90+ $ tox -e doc
91+
92+This will do two things:
93+
94+- Build the documentation using sphinx
95+- Run doc8 against the documentation source code
96+
97+Once build the HTML files will be viewable in ``doc/rtd_html``. Use your
98+web browser to open ``index.html`` to view and navigate the site.
99+
100+Style Guide
101+===========
102+
103+Headings
104+--------
105+The headings used across the documentation use the following hierarchy:
106+
107+- ``*****``: used once atop of a new page
108+- ``=====``: each sections on the page
109+- ``-----``: subsections
110+- ``^^^^^``: sub-subsections
111+- ``"""""``: paragraphs
112+
113+The top level header ``######`` is reserved for the first page.
114+
115+If under and overline are used, their length must be identical. The length of
116+the underline must be at least as long as the title itself
117+
118+Line Length
119+-----------
120+Please keep the line lengths to a maximum of **79** characters. This ensures
121+that the pages and tables do not get too wide that side scrolling is required.
122+
123+Header
124+------
125+Adding a link at the top of the page allows for the page to be referenced by
126+other pages. For example for the FAQ page this would be:
127+
128+.. code-block:: rst
129+
130+ .. _faq:
131+
132+Footer
133+------
134+The footer should include the textwidth
135+
136+.. code-block:: rst
137+
138+ .. vi: textwidth=79
139+
140+Vertical Whitespace
141+-------------------
142+One newline between each section helps ensure readability of the documentation
143+source code.
144+
145+Common Words
146+------------
147+There are some common words that should follow specific usage:
148+
149+- ``cloud-init``: always lower case with a hyphen, unless starting a sentence
150+ in which case only the 'C' is capitalized (e.g. ``Cloud-init``).
151+- ``metadata``: one word
152+- ``user data``: two words, not to be combined
153+- ``vendor data``: like user data, it is two words
154+
155+.. vi: textwidth=79
156diff --git a/tox.ini b/tox.ini
157index 1f01eb7..f5baf32 100644
158--- a/tox.ini
159+++ b/tox.ini
160@@ -53,8 +53,13 @@ exclude = .venv,.tox,dist,doc,*egg,.git,build,tools
161
162 [testenv:doc]
163 basepython = python3
164-deps = sphinx
165-commands = {envpython} -m sphinx {posargs:doc/rtd doc/rtd_html}
166+deps =
167+ doc8
168+ sphinx
169+ sphinx_rtd_theme
170+commands =
171+ {envpython} -m sphinx {posargs:doc/rtd doc/rtd_html}
172+ doc8 doc/rtd
173
174 [testenv:xenial]
175 commands =

Subscribers

People subscribed via source and target branches