From 685121ba5d21e99a3c55819dcef138658d12d7d5 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 5 Jan 2021 18:31:17 +0000 Subject: [PATCH] Workaround to include relative readme into docs directory The workaround is described in https://github.com/readthedocs/recommonmark/issues/191 It is not perfect, but it does the job --- README.md | 6 +++--- docs/conf.py | 12 ++++++++++-- docs/index.rst | 37 +++++-------------------------------- docs/readme.rst | 2 ++ docs/requirements.txt | 1 + 5 files changed, 21 insertions(+), 37 deletions(-) create mode 100644 docs/readme.rst diff --git a/README.md b/README.md index c997540..0842965 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ the main documentation files still use reStructuredText by default. Remember to install [wheel] version 0.31 or higher and use [twine] to upload your package to [PyPI] instead of `python setup.py release` for this to work, e.g.: -```commandline +```bash python setup.py sdist bdist_wheel twine upload dist/* ``` @@ -32,7 +32,7 @@ twine upload dist/* This project uses [pre-commit], please make sure to install it before making any changes: -```commandline +```bash pip install pre-commit cd pyscaffoldext-markdown pre-commit install @@ -40,7 +40,7 @@ pre-commit install It is a good idea to update the hooks to the latest version: -```commandline +```bash pre-commit autoupdate ``` diff --git a/docs/conf.py b/docs/conf.py index 2eb8e4a..7cc91b3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -87,17 +87,25 @@ # To configure AutoStructify def setup(app): from recommonmark.transform import AutoStructify + from m2r import MdInclude, convert params = { "auto_toc_tree_section": "Contents", "enable_eval_rst": True, - "enable_auto_doc_ref": True, + # "enable_auto_doc_ref": True, "enable_math": True, "enable_inline_math": True, } app.add_config_value("recommonmark_config", params, True) app.add_transform(AutoStructify) + # from m2r to make `mdinclude` work + app.add_config_value('no_underscore_emphasis', False, 'env') + app.add_config_value('m2r_parse_relative_links', False, 'env') + app.add_config_value('m2r_anonymous_references', False, 'env') + app.add_config_value('m2r_disable_inline_math', False, 'env') + app.add_directive('mdinclude', MdInclude) + # Additional parsers besides rst source_parsers = {".md": "recommonmark.parser.CommonMarkParser"} @@ -166,7 +174,7 @@ def setup(app): # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "alabaster" +html_theme = "sphinx_rtd_theme" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/index.rst b/docs/index.rst index 326d778..d8214ed 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,25 +2,8 @@ pyscaffoldext-markdown ====================== -This is the documentation of **pyscaffoldext-markdown**. - -.. note:: - - This is the main page of your project's `Sphinx`_ documentation. - It is formatted in `reStructuredText`_. Add additional pages - by creating rst-files in ``docs`` and adding them to the `toctree`_ below. - Use then `references`_ in order to link them from this page, e.g. - :ref:`authors` and :ref:`changes`. - - It is also possible to refer to the documentation of other Python packages - with the `Python domain syntax`_. By default you can reference the - documentation of `Sphinx`_, `Python`_, `NumPy`_, `SciPy`_, `matplotlib`_, - `Pandas`_, `Scikit-Learn`_. You can add more by extending the - ``intersphinx_mapping`` in your Sphinx's ``conf.py``. - - The pretty useful extension `autodoc`_ is activated by default and lets - you include documentation from docstrings. Docstrings can be written in - `Google style`_ (recommended!), `NumPy style`_ and `classical style`_. +PyScaffold_ extension which replaces reStructuredText_ formatted files +by Markdown_ format except for Sphinx_-related files. Contents @@ -29,6 +12,7 @@ Contents .. toctree:: :maxdepth: 2 + Quickstart License Authors Changelog @@ -42,18 +26,7 @@ Indices and tables * :ref:`modindex` * :ref:`search` -.. _toctree: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html +.. _PyScaffold: http://pyscaffold.org .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html -.. _references: http://www.sphinx-doc.org/en/stable/markup/inline.html -.. _Python domain syntax: http://sphinx-doc.org/domains.html#the-python-domain +.. _Markdown: https://daringfireball.net/projects/markdown/ .. _Sphinx: http://www.sphinx-doc.org/ -.. _Python: http://docs.python.org/ -.. _Numpy: http://docs.scipy.org/doc/numpy -.. _SciPy: http://docs.scipy.org/doc/scipy/reference/ -.. _matplotlib: https://matplotlib.org/contents.html# -.. _Pandas: http://pandas.pydata.org/pandas-docs/stable -.. _Scikit-Learn: http://scikit-learn.org/stable -.. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html -.. _Google style: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings -.. _NumPy style: https://numpydoc.readthedocs.io/en/latest/format.html -.. _classical style: http://www.sphinx-doc.org/en/stable/domains.html#info-field-lists diff --git a/docs/readme.rst b/docs/readme.rst new file mode 100644 index 0000000..0358e5c --- /dev/null +++ b/docs/readme.rst @@ -0,0 +1,2 @@ +.. _readme: +.. mdinclude:: ../README.md diff --git a/docs/requirements.txt b/docs/requirements.txt index d63a56e..2395594 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,6 +1,7 @@ # Requirements file for ReadTheDocs, check .readthedocs.yml. # To build the module reference correctly, make sure every external package # under `install_requires` in `setup.cfg` is also listed here! +m2r recommonmark sphinx>=3.2.1 sphinx_rtd_theme