Rework the documentation skeleton + adopt myst

NJITICC · Sep 1, 2020 · ac5f826 · ac5f826
1 parent f3007c0
commit ac5f826
Show file tree

Hide file tree

Showing 25 changed files with 138 additions and 74 deletions.
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1,10 @@
+---
+hide-toc: true
+---
+
+
+# Changelog
+
+## unreleased
+
+Initial release.
diff --git a/docs/changelog.rst b/docs/changelog.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -25,7 +25,7 @@
 # -- General configuration ---------------------------------------------------
 #
 
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.mathjax"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.mathjax", "myst_parser"]
 templates_path = ["_templates"]
 
 #

diff --git a/docs/contributing.rst b/docs/contributing.rst
diff --git a/docs/customisation.md b/docs/customisation.md
@@ -0,0 +1,9 @@
+# Customisation
+
+TODO: provide information about:
+
+- how the entire theme is designed with CSS variables and how to override them
+  - via `css_variables` in conf.py (recommended, if you're not adding more CSS)
+  - custom CSS files
+- how `basic` theme's variables can be set but won't do s***
+- and finally, go read references for specific elements!
diff --git a/docs/customisation.rst b/docs/customisation.rst
diff --git a/docs/demo/index.md b/docs/demo/index.md
@@ -0,0 +1,20 @@
+# Sphinx RTD Theme's Demo Documentation
+
+All the pages within this section are copied over straight from
+[Sphinx ReadTheDocs Theme]'s "DEMO DOCUMENTATION" section.
+
+```{toctree}
+:maxdepth: 1
+demo
+lists_tables
+api
+long
+structure
+```
+
+Huge shoutout to everyone who's worked on `sphinx-rtd-theme`, since it was
+an absolutely essential reference for how to do things well.
+
+The folks at ReadTheDocs are doing really important work. [TODO: say something about how ethical ads as awesome, and call-to-action pointing to RTD's sustainability page]
+
+[Sphinx ReadTheDocs Theme]: https://sphinx-rtd-theme.readthedocs.io/en/stable/
diff --git a/docs/demo/index.rst b/docs/demo/index.rst
diff --git a/docs/development/design-goals.md b/docs/development/design-goals.md
@@ -0,0 +1,13 @@
+# Design Goals
+
+TODO: Write this.
+
+- why I wrote this.
+  - good navigational capabilities in sidebar
+  - "content in the middle" three-column layout
+  - inspired by justthedocs and mkdocs-material
+- what were the guiding ideas?
+  - content is the focus
+  - more stuff is not more good
+  - graceful degradation
+  - no need to look the same everywhere
diff --git a/docs/development/getting-started.md b/docs/development/getting-started.md
@@ -0,0 +1,7 @@
+# Getting Started
+
+TODO: write this
+
+- 5-sentence overview of development workflow.
+- how to get set up (if you have Python and Node setup).
+- what the various nox commands are.
diff --git a/docs/development/index.md b/docs/development/index.md
@@ -0,0 +1,17 @@
+# Development
+
+TODO: write a welcome message and describe how this section of the
+documentation is layed out.
+
+```{toctree}
+:maxdepth: 1
+getting-started
+internals
+design-goals
+```
+
+TODO: provide information about:
+
+- CoC
+- @pradyunsg is the BDFL.
+- open to making changes? Yes, even drastic ones if there's a strong case.
diff --git a/docs/development/internals.md b/docs/development/internals.md
@@ -0,0 +1,11 @@
+# Internals
+
+TODO: This page will provide an overview of the "internals" of the development process.
+
+- How the repository is layed out.
+- How the theme is built, for development and for release.
+- How all the code-supported components work.
+  - CSS variables
+  - Navigation
+  - Contents
+  - Tables + Code backgrounds
diff --git a/docs/features.rst b/docs/features.rst
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,19 @@
+# Home
+
+See `_templates/layouts/home.html` for the actual homepage HTML. This file only serves to provide the correct toctree to Sphinx.
+
+```{toctree}
+quickstart
+customisation
+reference/index
+development/index
+changelog
+license
+```
+
+```{toctree}
+:caption: Kitchen Sink
+
+GitHub Repository <https://github.com/pradyunsg/mawek>
+demo/index
+```
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/introduction.rst b/docs/introduction.rst
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -0,0 +1,3 @@
+# Quickstart
+
+TODO: I still need to write this.
diff --git a/docs/recommendations.rst b/docs/recommendations.rst
diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
@@ -0,0 +1,3 @@
+# Admonitions
+
+TODO: provides a reference to how to customize the admonitions, and how to add custom admonitions.
diff --git a/docs/reference/colors.md b/docs/reference/colors.md
@@ -0,0 +1,3 @@
+# Colors
+
+TODO: provides a reference to how to customize the colors for various things.
diff --git a/docs/reference/fonts.md b/docs/reference/fonts.md
@@ -0,0 +1,3 @@
+# Fonts
+
+TODO: provides a reference to how to customize the fonts (--font-size) and friends.
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -0,0 +1,12 @@
+# Reference
+
+```{toctree}
+:caption: Reference for various elements
+:maxdepth: 1
+
+admonitions
+colors
+fonts
+nav-sidebar
+toc-sidebar
+```
diff --git a/docs/reference/nav-sidebar.md b/docs/reference/nav-sidebar.md
@@ -0,0 +1,3 @@
+# Navigation Sidebar
+
+TODO: provides a reference to how to customize the sidebar and it's contents.
diff --git a/docs/reference/toc-sidebar.md b/docs/reference/toc-sidebar.md
@@ -0,0 +1,3 @@
+# Contents Sidebar
+
+TODO: provides a reference to how to customize the sidebar and it's contents.
diff --git a/pyproject.toml b/pyproject.toml
@@ -19,7 +19,7 @@ test = [
   "pytest-cov",
   "pytest-xdist",
 ]
-doc = ["sphinx"]
+doc = ["sphinx", "myst-parser"]
 
 [tool.flit.entrypoints]
 "sphinx.html_themes" = {mawek = "mawek"}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Quickstart

		TODO: I still need to write this.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Admonitions

		TODO: provides a reference to how to customize the admonitions, and how to add custom admonitions.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Colors

		TODO: provides a reference to how to customize the colors for various things.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Fonts

		TODO: provides a reference to how to customize the fonts (--font-size) and friends.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Navigation Sidebar

		TODO: provides a reference to how to customize the sidebar and it's contents.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Contents Sidebar

		TODO: provides a reference to how to customize the sidebar and it's contents.