Skip to content

Commit 741896d

Browse files
daksmyii
daks
authored and
myii
committed
docs: move contributing sections and links to ease adaptation
1 parent cf3212d commit 741896d

File tree

4 files changed

+101
-88
lines changed

4 files changed

+101
-88
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,3 +108,6 @@ Gemfile.lock
108108

109109
# copied `.md` files used for conversion to `.rst` using `m2r`
110110
docs/*.md
111+
112+
# Vim
113+
*.sw?

‎docs/CONTRIBUTING.rst‎

Lines changed: 1 addition & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -180,87 +180,5 @@ These formulas are already compatible with semantic-release:
180180
Documentation
181181
-------------
182182

183-
Toolchain
184-
^^^^^^^^^
185-
186-
The documentation for this formula is written in
187-
`reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_
188-
(also known as RST, ReST, or reST).
189-
It is built by
190-
`Sphinx <https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_
191-
and hosted on
192-
`Read the Docs <https://en.wikipedia.org/wiki/Read_the_Docs>`_.
193-
194-
Adding a new page
195-
^^^^^^^^^^^^^^^^^
196-
197-
Adding a new page involves two steps:
198-
199-
#. Use the
200-
:ref:`provided page template <saltstack_formulas_rst_page_template>`
201-
to create a new page.
202-
#. Add the page name under the ``toctree`` list in ``index.rst``.
203-
204-
a. Do not just append it to the list.
205-
#. Select the best place where it fits within the overall documentation.
206-
207-
SaltStack-Formulas' RST page template
208-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
209-
210-
.. _saltstack_formulas_rst_page_template
211-
212-
Use the following template when creating a new page.
213-
This ensures consistency across the documentation for this formula.
214-
The heading symbols have been selected in accordance to the output rendered by the
215-
`Markdown to reStructuredText converter <https://github.com/miyakogi/m2r#restrictions>`_
216-
we are using for some of the pages of this documentation.
217-
218-
.. code-block:: rst
219-
220-
.. _template:
221-
222-
[Page title]
223-
============
224-
225-
[Introductory paragraph]
226-
227-
.. contents:: **Table of Contents**
228-
229-
[Heading 2]
230-
-----------
231-
232-
[Heading 3]
233-
^^^^^^^^^^^
234-
235-
[Heading 4]
236-
~~~~~~~~~~~
237-
238-
[Heading 5]
239-
"""""""""""
240-
241-
[Heading 6]
242-
###########
243-
244-
#. The first line is an anchor that can be used to link back to (the top of)
245-
this file.
246-
247-
a. Change this to be the lowercase version of the file name.
248-
#. Do not include the ``.rst`` file extension.
249-
#. Use hyphens (``-``) instead of spaces or non-letter characters.
250-
251-
#. Change the ``[Page title]`` accordingly, matching the same number of equals
252-
signs (``=``) underneath.
253-
#. Change the ``[Introductory paragraph]`` to be a short summary of the page
254-
content.
255-
Use no more than three paragraphs for this.
256-
#. Leave the ``..contents:: **Table of Contents**`` line as it is.
257-
#. Use the remaining headings as required to break up the page content.
258-
259-
a. You will rarely need to use beyond ``[Heading 4]``.
260-
#. Again, no single heading should have more than about three paragraphs of
261-
content before the next heading or sub-heading is used.
262-
263-
Obviously, it is not necessary to follow the steps in the order above.
264-
For example, it is usually easier to write the ``[Introductory paragraph]``
265-
at the end.
183+
`Documentation contributing guidelines <CONTRIBUTING_DOCS>`
266184

‎docs/CONTRIBUTING_DOCS.rst‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
.. _contributing_docs:
2+
3+
Contributing documentation
4+
==========================
5+
6+
|docs|
7+
8+
.. |docs| image:: https://readthedocs.org/projects/docs/badge/?version=latest
9+
:alt: Documentation Status
10+
:scale: 100%
11+
:target: https://template-formula.readthedocs.io/en/latest/?badge=latest
12+
13+
Toolchain
14+
^^^^^^^^^
15+
16+
The documentation for this formula is written in
17+
`reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_
18+
(also known as RST, ReST, or reST).
19+
It is built by
20+
`Sphinx <https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_
21+
and hosted on
22+
`Read the Docs <https://en.wikipedia.org/wiki/Read_the_Docs>`_.
23+
24+
Adding a new page
25+
^^^^^^^^^^^^^^^^^
26+
27+
Adding a new page involves two steps:
28+
29+
#. Use the
30+
:ref:`provided page template <saltstack_formulas_rst_page_template>`
31+
to create a new page.
32+
#. Add the page name under the ``toctree`` list in ``index.rst``.
33+
34+
a. Do not just append it to the list.
35+
#. Select the best place where it fits within the overall documentation.
36+
37+
SaltStack-Formulas' RST page template
38+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
39+
40+
.. _saltstack_formulas_rst_page_template
41+
42+
Use the following template when creating a new page.
43+
This ensures consistency across the documentation for this formula.
44+
The heading symbols have been selected in accordance to the output rendered by the
45+
`Markdown to reStructuredText converter <https://github.com/miyakogi/m2r#restrictions>`_
46+
we are using for some of the pages of this documentation.
47+
48+
.. code-block:: rst
49+
50+
.. _template:
51+
52+
[Page title]
53+
============
54+
55+
[Introductory paragraph]
56+
57+
.. contents:: **Table of Contents**
58+
59+
[Heading 2]
60+
-----------
61+
62+
[Heading 3]
63+
^^^^^^^^^^^
64+
65+
[Heading 4]
66+
~~~~~~~~~~~
67+
68+
[Heading 5]
69+
"""""""""""
70+
71+
[Heading 6]
72+
###########
73+
74+
#. The first line is an anchor that can be used to link back to (the top of)
75+
this file.
76+
77+
a. Change this to be the lowercase version of the file name.
78+
#. Do not include the ``.rst`` file extension.
79+
#. Use hyphens (``-``) instead of spaces or non-letter characters.
80+
81+
#. Change the ``[Page title]`` accordingly, matching the same number of equals
82+
signs (``=``) underneath.
83+
#. Change the ``[Introductory paragraph]`` to be a short summary of the page
84+
content.
85+
Use no more than three paragraphs for this.
86+
#. Leave the ``..contents:: **Table of Contents**`` line as it is.
87+
#. Use the remaining headings as required to break up the page content.
88+
89+
a. You will rarely need to use beyond ``[Heading 4]``.
90+
#. Again, no single heading should have more than about three paragraphs of
91+
content before the next heading or sub-heading is used.
92+
93+
Obviously, it is not necessary to follow the steps in the order above.
94+
For example, it is usually easier to write the ``[Introductory paragraph]``
95+
at the end.
96+

‎docs/README.rst‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,12 @@
33
template-formula
44
================
55

6-
|img_travis| |docs| |img_sr|
6+
|img_travis| |img_sr|
77

88
.. |img_travis| image:: https://travis-ci.com/saltstack-formulas/template-formula.svg?branch=master
99
:alt: Travis CI Build Status
1010
:scale: 100%
1111
:target: https://travis-ci.com/saltstack-formulas/template-formula
12-
.. |docs| image:: https://readthedocs.org/projects/docs/badge/?version=latest
13-
:alt: Documentation Status
14-
:scale: 100%
15-
:target: https://template-formula.readthedocs.io/en/latest/?badge=latest
1612
.. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
1713
:alt: Semantic Release
1814
:scale: 100%

0 commit comments

Comments
 (0)