diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index fdd7c1884..5a715332e 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -31,7 +31,7 @@ Strive to keep any contributions relevant to the :ref:`purpose of The Guide relate to Python development. * Prefer to link to other sources if the information is already out there. Be sure to describe what and why you are linking. -* `Cite `_ +* `Cite `_ references where needed. * If a subject isn't directly relevant to Python, but useful in conjunction with Python (e.g., Git, GitHub, Databases), reference by linking to useful @@ -146,14 +146,14 @@ Externally Linking Sphinx_ is used to document Python. - .. _Sphinx: http://sphinx.pocoo.org + .. _Sphinx: https://www.sphinx-doc.org * Prefer to use descriptive labels with inline links instead of leaving bare links: .. code-block:: rest - Read the `Sphinx Tutorial `_ + Read the `Sphinx Tutorial `_ * Avoid using labels such as "click here", "this", etc., preferring descriptive labels (SEO worthy) instead. @@ -164,7 +164,7 @@ Linking to Sections in The Guide ******************************** To cross-reference other parts of this documentation, use the `:ref: -`_ +`_ keyword and labels. To make reference labels more clear and unique, always add a ``-ref`` suffix: @@ -182,7 +182,7 @@ Notes and Warnings ****************** Make use of the appropriate `admonitions directives -`_ when making notes. +`_ when making notes. Notes: @@ -205,7 +205,7 @@ TODOs ***** Please mark any incomplete areas of The Guide with a `todo directive -`_. To +`_. To avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub documents or large incomplete sections. diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index c0d93d86c..4d72a544d 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -85,7 +85,7 @@ structured and easily readable documentation for your project. for general project documentation. This Guide is built with Sphinx_ and is hosted on `Read The Docs`_ -.. _Sphinx: http://sphinx.pocoo.org +.. _Sphinx: https://www.sphinx-doc.org .. _Read The Docs: http://readthedocs.org .. _restructuredtext-ref: @@ -100,7 +100,7 @@ The `reStructuredText Primer`_ and the `reStructuredText Quick Reference`_ should help you familiarize yourself with its syntax. .. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _reStructuredText Primer: http://sphinx.pocoo.org/rest.html +.. _reStructuredText Primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _reStructuredText Quick Reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html