IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

doc: Address review comments

Browse Source 
These came up in the review for pull request #4799.

Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane 2018-04-30 10:21:34 +01:00
parent 16e76faba3
commit 0bf8886fc4
2 changed files with 18 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/usage/configuration.rst
View File

@ -2485,5 +2485,5 @@ Options for the C++ domain
Example of configuration file Example of configuration file
============================= =============================
.. literalinclude:: ../_static/conf.py.txt .. literalinclude:: /_static/conf.py.txt
:language: python :language: python

30
doc/usage/markdown.rst
View File

@ -1,21 +1,28 @@
.. highlight:: python .. highlight:: python
.. _markdown:
======== ========
Markdown Markdown
======== ========
`Markdown`_ is a lightweight markup language with a simplistic plain text `Markdown`__ is a lightweight markup language with a simplistic plain text
formatting syntax. It exists in many syntactically different *flavors*. To formatting syntax. It exists in many syntactically different *flavors*. To
support Markdown-based documentation, Sphinx can use `recommonmark`_. support Markdown-based documentation, Sphinx can use `recommonmark`__.
recommonmark is a Docutils bridge to `CommonMark-py`_, a Python package for recommonmark is a Docutils bridge to `CommonMark-py`__, a Python package for
parsing the `CommonMark`_ Markdown flavor. parsing the `CommonMark`__ Markdown flavor.
__ https://daringfireball.net/projects/markdown/
__ https://recommonmark.readthedocs.io/en/latest/index.html
__ https://github.com/rtfd/CommonMark-py
__ http://commonmark.org/
Configuration Configuration
------------- -------------
To configure your Sphinx project for Markdown support, proceed as follows: To configure your Sphinx project for Markdown support, proceed as follows:
#. Install recommonmark:: #. Install *recommonmark*::
pip install recommonmark pip install recommonmark
@ -26,18 +33,15 @@ To configure your Sphinx project for Markdown support, proceed as follows:
'.md': 'recommonmark.parser.CommonMarkParser', '.md': 'recommonmark.parser.CommonMarkParser',
} }
You can replace `.md` with a filename extension of your choice. You can replace ``.md`` with a filename extension of your choice.
#. Add the Markdown filename extension to the ``source_suffix`` configuration #. Add the Markdown filename extension to the ``source_suffix`` configuration
variable:: variable::
source_suffix = ['.rst', '.md'] source_suffix = ['.rst', '.md']
#. You can further configure recommonmark to allow custom syntax that standard #. You can further configure *recommonmark* to allow custom syntax that
CommonMark doesn't support. Read more in the `recommonmark documentation standard *CommonMark* doesn't support. Read more in the `recommonmark
<shttp://recommonmark.readthedocs.io/en/latest/auto_structify.html>`__. documentation`__.
.. _Markdown: https://daringfireball.net/projects/markdown/ __ https://recommonmark.readthedocs.io/en/latest/auto_structify.html
.. _recommonmark: https://recommonmark.readthedocs.io/en/latest/index.html
.. _CommonMark-py: <https://github.com/rtfd/CommonMark-py>
.. _CommonMark: http://commonmark.org/