reorganizing docs and using pydata theme (#45)

executablebooks · Feb 15, 2020 · 4150051 · 4150051
1 parent e8e1e97
commit 4150051
Show file tree

Hide file tree

Showing 15 changed files with 54 additions and 28 deletions.
diff --git a/docs/_static/logo.png b/docs/_static/logo.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -28,10 +28,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    "myst_parser",
-    "sphinxcontrib.bibtex",
-]
+extensions = ["myst_parser", "sphinxcontrib.bibtex"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -47,7 +44,8 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "pandas_sphinx_theme"
+html_logo = "_static/logo.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

diff --git a/docs/contributing.md → docs/develop/contributing.md b/docs/contributing.md → docs/develop/contributing.md
diff --git a/docs/develop/index.md b/docs/develop/index.md
@@ -0,0 +1,8 @@
+# Contribute to MyST
+
+This section covers documentation relevant to developing and maintaining the MyST
+codebase, and some guidelines for how you can contribute.
+
+```{toctree}
+contributing.md
+```
diff --git a/docs/heavy_tails.md → docs/examples/heavy_tails.md b/docs/heavy_tails.md → docs/examples/heavy_tails.md
@@ -1 +1,5 @@
+---
+orphan: true
+---
+
 # DUMMY DOCUMENT FOR TESTING :doc: ROLE
diff --git a/docs/htop_again.png → docs/examples/htop_again.png b/docs/htop_again.png → docs/examples/htop_again.png
diff --git a/docs/examples/index.md b/docs/examples/index.md
@@ -0,0 +1,12 @@
+# Example documents
+
+The following pages are examples meant to highlight the functionality of
+Myst documents.
+
+```{toctree}
+---
+caption: Compare rST and MyST versions
+---
+wealth_dynamics_rst.rst
+wealth_dynamics_md.md
+```
diff --git a/docs/kesten_processes.md → docs/examples/kesten_processes.md b/docs/kesten_processes.md → docs/examples/kesten_processes.md
@@ -1 +1,4 @@
+---
+orphan: true
+---
 # DUMMY DOCUMENT FOR TESTING :doc: ROLE
diff --git a/docs/references.bib → docs/examples/references.bib b/docs/references.bib → docs/examples/references.bib
diff --git a/docs/wealth_dynamics_md.md → docs/examples/wealth_dynamics_md.md b/docs/wealth_dynamics_md.md → docs/examples/wealth_dynamics_md.md
@@ -1,4 +1,4 @@
-# Wealth Distribution Dynamics
+# Wealth Distribution Dynamics in MyST
 
 In addition to what's in Anaconda, this lecture will need the following
 libraries:

diff --git a/docs/wealth_dynamics_rst.rst → docs/examples/wealth_dynamics_rst.rst b/docs/wealth_dynamics_rst.rst → docs/examples/wealth_dynamics_rst.rst
@@ -1,9 +1,9 @@
 .. highlight:: python3
 
 
-****************************
-Wealth Distribution Dynamics
-****************************
+***********************************
+Wealth Distribution Dynamics in rST
+***********************************
 
 .. contents:: :depth: 2
 

diff --git a/docs/index.md b/docs/index.md
@@ -33,22 +33,7 @@ Here are the site contents:
 maxdepth: 2
 caption: Contents
 ---
-syntax.md
-contributing.md
-```
-
-```{toctree}
----
-caption: Example pages
----
-wealth_dynamics_rst.rst
-wealth_dynamics_md.md
-```
-
-```{toctree}
----
-hidden: True
----
-heavy_tails.md
-kesten_processes.md
+using/index.md
+examples/index.md
+develop/index.md
 ```
diff --git a/docs/using/index.md b/docs/using/index.md
@@ -0,0 +1,8 @@
+# Using MyST
+
+The following pages are examples meant to highlight the functionality of
+Myst documents.
+
+```{toctree}
+syntax.md
+```
diff --git a/docs/syntax.md → docs/using/syntax.md b/docs/syntax.md → docs/using/syntax.md
diff --git a/setup.py b/setup.py
@@ -40,7 +40,15 @@
         )
     ],
     extras_require={
-        "sphinx": ["pyyaml", "docutils>=0.15", "sphinx>=2,<3"],
+        "sphinx": [
+            "pyyaml",
+            "docutils>=0.15",
+            "sphinx>=2,<3",
+            (
+                "pandas_sphinx_theme @ "
+                "https://github.com/pandas-dev/pandas-sphinx-theme/archive/master.zip"
+            ),
+        ],
         "code_style": ["flake8<3.8.0,>=3.7.0", "black", "pre-commit==1.17.0"],
         "testing": [
             "coverage",