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