Merge pull request #9 from pyscaffold/rtd_setup

Rtd setup

.readthedocs.yml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+
+python:
+  version: 3.8
+  install:
+    - requirements: docs/requirements.txt

README.md

@@ -1,4 +1,5 @@
 [![Build Status](https://api.cirrus-ci.com/github/pyscaffold/pyscaffoldext-dsproject.svg?branch=master)](https://cirrus-ci.com/github/pyscaffold/pyscaffoldext-dsproject)
+[![ReadTheDocs](https://readthedocs.org/projects/pyscaffold/badge/?version=latest)](https://pyscaffoldext-dsproject.readthedocs.io)
 [![Coveralls](https://img.shields.io/coveralls/github/pyscaffold/pyscaffoldext-dsproject/master.svg)](https://coveralls.io/r/pyscaffold/pyscaffoldext-dsproject)
 [![PyPI-Server](https://img.shields.io/pypi/v/pyscaffoldext-dsproject.svg)](https://pypi.org/project/pyscaffoldext-dsproject)
 [![Downloads](https://pepy.tech/badge/pyscaffoldext-dsproject/month)](https://pepy.tech/project/pyscaffoldext-dsproject)
@@ -61,7 +62,7 @@ the documentation of [PyScaffold] for more information.
 Just install this package with `pip install pyscaffoldext-dsproject`
 and note that `putup -h` shows a new option `--dsproject`.
 Creating a data science project is then as easy as:
-```
+```bash
 putup --dsproject my_ds_project
 ```
 
@@ -73,15 +74,15 @@ putup --dsproject my_ds_project
 This project uses [pre-commit], please make sure to install it before making any
 changes:
 
-```commandline
+```bash
 pip install pre-commit
 cd pyscaffoldext-dsproject
 pre-commit install
 ```
 
 It is a good idea to update the hooks to the latest version:
 
-```commandline
+```bash
 pre-commit autoupdate
 ```
 

docs/conf.py

@@ -46,7 +46,9 @@
 try:
     import sphinx
 
-    cmd_line_template = "sphinx-apidoc -f -o {outputdir} {moduledir}"
+    cmd_line_template = (
+        "sphinx-apidoc --implicit-namespaces -f -o {outputdir} {moduledir}"
+    )
     cmd_line = cmd_line_template.format(outputdir=output_dir, moduledir=module_dir)
 
     args = cmd_line.split(" ")
@@ -76,13 +78,32 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
+    "sphinx.ext.extlinks",
+    "recommonmark",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+# To configure AutoStructify
+def setup(app):
+    from recommonmark.transform import AutoStructify
+
+    params = {
+        "auto_toc_tree_section": "Contents",
+        "enable_eval_rst": True,
+        "enable_math": True,
+        "enable_inline_math": True,
+    }
+    app.add_config_value("recommonmark_config", params, True)
+    app.add_transform(AutoStructify)
+
+
+# Additional parsers besides rst
+source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}
+
 # The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -145,14 +166,14 @@
 
 # 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
 # documentation.
 html_theme_options = {
-    "sidebar_width": "300px",
-    "page_width": "1200px"
+#   "sidebar_width": "300px",
+#   "page_width": "1200px"
 }
 
 # Add any paths that contain custom themes here, relative to this directory.

docs/index.rst

@@ -2,25 +2,7 @@
 pyscaffoldext-dsproject
 =======================
 
-This is the documentation of **pyscaffoldext-dsproject**.
-
-.. 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 that adds a perfect structure for Data Science projects.
 
 
 Contents
@@ -29,6 +11,7 @@ Contents
 .. toctree::
    :maxdepth: 2
 
+   Overview <readme>
    License <license>
    Authors <authors>
    Changelog <changelog>

docs/readme.md

@@ -0,0 +1 @@
+../README.md

docs/requirements.txt

@@ -0,0 +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!
+pyscaffold
+recommonmark
+sphinx>=3.2.1
+sphinx_rtd_theme