@@ -21,7 +21,8 @@ To get started, check out and configure the repository for development::
2121
2222 In case of windows, run ``configure --dev ``.
2323
24- This will install and configure all requirements foer development including for docs development.
24+ This will install and configure all requirements
25+ for development including for docs development.
2526
2627Now you can build the HTML documentation locally::
2728
@@ -45,8 +46,10 @@ To validate the documentation style and content, use::
4546Continuous Integration
4647----------------------
4748
48- The documentations are checked on every new commit, so that common errors are avoided and
49- documentation standards are enforced. We checks for these aspects of the documentation:
49+ The documentations are checked on every new commit,
50+ so that common errors are avoided and
51+ documentation standards are enforced.
52+ We checks for these aspects of the documentation:
5053
51541. Successful Builds (By using ``sphinx-build ``)
52552. No Broken Links (By Using ``linkcheck ``)
@@ -90,7 +93,8 @@ A sample output is::
9093 - CheckTrailingWhitespace = 47
9194 - CheckValidity = 1
9295
93- Now fix the errors and run again till there isn't any style error in the documentation.
96+ Now fix the errors and run again till there isn't
97+ any style error in the documentation.
9498
9599
96100What is Checked?
@@ -123,7 +127,8 @@ Interspinx
123127
124128AboutCode documentation uses
125129`Intersphinx <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html >`_
126- to link to other Sphinx Documentations, to maintain links to other Aboutcode Projects.
130+ to link to other Sphinx Documentations,
131+ to maintain links to other Aboutcode Projects.
127132
128133To link sections in the same documentation, standart reST labels are used. Refer
129134`Cross-Referencing <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html >`_
@@ -140,10 +145,13 @@ For example::
140145
141146 It refers to the section itself, see :ref:`my-reference-label`.
142147
143- Now, using Intersphinx, you can create these labels in one Sphinx Documentation and then referance
144- these labels from another Sphinx Documentation, hosted in different locations.
148+ Now, using Intersphinx, you can create these labels in
149+ one Sphinx Documentation and then referance
150+ these labels from another Sphinx Documentation,
151+ hosted in different locations.
145152
146- You just have to add the following in the ``conf.py `` file for your Sphinx Documentation, where you
153+ You just have to add the following in the ``conf.py `` file
154+ for your Sphinx Documentation, where you
147155want to add the links::
148156
149157 extensions = [
@@ -161,18 +169,24 @@ To show all Intersphinx links and their targets of an Intersphinx mapping file,
161169 ``python -msphinx.ext.intersphinx https://aboutcode.readthedocs.io/objects.inv `` will give
162170 error.
163171
164- This enables you to create links to the ``aboutcode `` Documentation in your own Documentation,
165- where you modified the configuration file. Links can be added like this::
172+ This enables you to create links to the ``aboutcode ``
173+ Documentation in your own Documentation,
174+ where you modified the configuration file.
175+ Links can be added like this::
166176
167177 For more details refer :ref:`aboutcode:doc_style_guide`.
168178
169- You can also not use the ``aboutcode `` label assigned to all links from aboutcode.readthedocs.io,
170- if you don't have a label having the same name in your Sphinx Documentation. Example::
179+ You can also not use the ``aboutcode `` label assigned
180+ to all links from aboutcode.readthedocs.io,
181+ if you don't have a label having the same name in your
182+ Sphinx Documentation. Example::
171183
172184 For more details refer :ref:`doc_style_guide`.
173185
174- If you have a label in your documentation which is also present in the documentation linked by
175- Intersphinx, and you link to that label, it will create a link to the local label.
186+ If you have a label in your documentation
187+ which is also present in the documentation linked by
188+ Intersphinx, and you link to that label,
189+ it will create a link to the local label.
176190
177191For more information, refer this tutorial named
178192`Using Intersphinx <https://my-favorite-documentation-test.readthedocs.io/en/latest/using_intersphinx.html >`_.
@@ -186,8 +200,10 @@ Style Conventions for the Documentaion
1862001. Headings
187201
188202 (`Refer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections >`_)
189- Normally, there are no heading levels assigned to certain characters as the structure is
190- determined from the succession of headings. However, this convention is used in Python’s Style
203+ Normally, there are no heading levels assigned to
204+ certain characters as the structure is
205+ determined from the succession of headings.
206+ However, this convention is used in Python’s Style
191207 Guide for documenting which you may follow:
192208
193209 # with overline, for parts
@@ -204,7 +220,8 @@ Style Conventions for the Documentaion
204220
2052212. Heading Underlines
206222
207- Do not use underlines that are longer/shorter than the title headline itself. As in:
223+ Do not use underlines that are longer/shorter than
224+ the title headline itself. As in:
208225
209226 ::
210227
@@ -220,42 +237,57 @@ Style Conventions for the Documentaion
220237
221238.. note ::
222239
223- Underlines shorter than the Title text generates Errors on sphinx-build.
240+ Underlines shorter than the Title text generates Errors
241+ on sphinx-build.
224242
225243
2262443. Internal Links
227245
228- Using ``:ref: `` is advised over standard reStructuredText links to sections (like
229- ```Section title`_ ``) because it works across files, when section headings are changed, will
230- raise warnings if incorrect, and works for all builders that support cross-references.
231- However, external links are created by using the standard ```Section title`_ `` method.
246+ Using ``:ref: `` is advised over standard reStructuredText
247+ links to sections (like ```Section title`_ ``) because it works
248+ across files, when section headings are changed, will raise
249+ warnings if incorrect, and works for all builders that support
250+ cross-references. However, external links are created by
251+ using the standard ```Section title`_ `` method.
232252
2332534. Eliminate Redundancy
234254
235- If a section/file has to be repeated somewhere else, do not write the exact same section/file
236- twice. Use ``.. include: ../README.rst `` instead. Here, ``../ `` refers to the documentation
237- root, so file location can be used accordingly. This enables us to link documents from other
255+ If a section/file has to be repeated somewhere else,
256+ do not write the exact same section/file twice.
257+ Use ``.. include: ../README.rst `` instead. Here, ``../ ``
258+ refers to the documentation root, so file location can
259+ be used accordingly. This enables us to link documents from other
238260 upstream folders.
239261
2402625. Using ``:ref: `` only when necessary
241263
242- Use ``:ref: `` to create internal links only when needed, i.e. it is referenced somewhere.
243- Do not create references for all the sections and then only reference some of them, because
244- this created unnecessary references. This also generates ERROR in ``restructuredtext-lint ``.
264+ Use ``:ref: `` to create internal links only when needed,
265+ i.e. it is referenced somewhere.
266+ Do not create references for all the
267+ sections and then only reference some of them, because
268+ this created unnecessary references.
269+ This also generates ERROR in ``restructuredtext-lint ``.
245270
2462716. Spelling
247272
248- You should check for spelling errors before you push changes. `Aspell <http://aspell.net/ >`_
249- is a GNU project Command Line tool you can use for this purpose. Download and install Aspell,
250- then execute ``aspell check <file-name> `` for all the files changed. Be careful about not
251- changing commands or other stuff as Aspell gives prompts for a lot of them. Also delete the
252- temporary ``.bak `` files generated. Refer the `manual <http://aspell.net/man-html/ >`_ for more
273+ You should check for spelling errors before
274+ you push changes. `Aspell <http://aspell.net/ >`_
275+ is a GNU project Command Line tool you can use
276+ for this purpose. Download and install Aspell,
277+ then execute ``aspell check <file-name> `` for all
278+ the files changed. Be careful about not
279+ changing commands or other stuff as Aspell
280+ gives prompts for a lot of them. Also delete the
281+ temporary ``.bak `` files generated. Refer the
282+ `manual <http://aspell.net/man-html/ >`_ for more
253283 information on how to use.
254284
2552857. Notes and Warning Snippets
256286
257- Every ``Note `` and ``Warning `` sections are to be kept in ``rst_snippets/note_snippets/ `` and
258- ``rst_snippets/warning_snippets/ `` and then included to eliminate redundancy, as these are
287+ Every ``Note `` and ``Warning `` sections are
288+ to be kept in ``rst_snippets/note_snippets/ `` and
289+ ``rst_snippets/warning_snippets/ `` and then
290+ included to eliminate redundancy, as these are
259291 frequently used in multiple files.
260292
261293
@@ -264,8 +296,9 @@ Converting from Markdown
264296
265297If you want to convert a ``.md `` file to a ``.rst `` file, this
266298`tool <https://github.com/chrissimpkins/md2rst >`_ does it pretty well.
267- You will still have to clean up and check for errors as this contains a lot of bugs. But this is
299+ You will still have to clean up and check for errors
300+ as this contains a lot of bugs. But this is
268301definitely better than converting everything by yourself.
269-
270- This will be helpful in converting GitHub wiki's (Markdown Files) to reStructuredtext files for
302+ This will be helpful in converting GitHub wiki's
303+ (Markdown Files) to reStructuredtext files for
271304Sphinx/ReadTheDocs hosting.
0 commit comments