Merge pull request #9 from choldgraf/docs-update

Add demo documentation site and unpin book theme

.gitignore

@@ -109,6 +109,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+.nox
 
 # Spyder project settings
 .spyderproject

README.md

@@ -6,3 +6,24 @@ This is a theme for [Sphinx](http://sphinx-doc.org/) that inherits from the
 [Sphinx Book Theme](https://github.com/executablebooks/sphinx-book-theme).
 
 It is used for the [Pangeo Forge documentation](https://pangeo-forge.readthedocs.io/en/latest/) and related projects.
+
+## Build the documentation
+
+This site comes bundled with a small documentation site to make it easy to preview what the theme looks like.
+
+The easiest way to build the documentation is to us [the nox command line tool](https://nox.thea.codes/).
+This is kind-of like a `Makefile` that is bundled with an isolated local environment.
+
+To build the documentation with `nox`, run this command:
+
+```
+nox -s docs
+```
+
+To build the documentation with a live server that auto-reloads when you make changes to `docs/`, run this command:
+
+```
+nox -s docs-live
+```
+
+Configuration for `nox` can be found in `noxfile.py`.

docs/conf.py

@@ -0,0 +1,7 @@
+project = "Pangeo Book Theme"
+html_title = "Pangeo Book Theme"
+html_theme = "pangeo_sphinx_book_theme"
+extensions = ["sphinx.ext.autodoc"]
+
+# Uncomment to test non-default logo
+# html_logo = "_static/pangeo-forge-logo-blue.png"

docs/index.rst

@@ -0,0 +1,10 @@
+Test documentation
+==================
+
+This is simple documentation to test the Pangeo Book Theme.
+All of the pages in this demo site are taken from the Kitchen Sink of `the Sphinx Themes gallery <https://github.com/sphinx-themes/sphinx-themes.org>`_.
+
+.. toctree::
+   :glob:
+
+   kitchen-sink/*

docs/kitchen-sink/admonitions.rst

@@ -0,0 +1,123 @@
+..
+   Copyright (c) 2021 Pradyun Gedam
+   Licensed under Creative Commons Attribution-ShareAlike 4.0 International License
+   SPDX-License-Identifier: CC-BY-SA-4.0
+
+===========
+Admonitions
+===========
+
+Sphinx provides several different types of admonitions.
+
+``topic``
+=========
+
+.. topic:: This is a topic.
+
+   This is what admonitions are a special case of, according to the docutils
+   documentation.
+
+``admonition``
+==============
+
+.. admonition:: The one with the custom titles
+
+   It's got a certain charm to it.
+
+``attention``
+=============
+
+.. attention::
+
+   Climate change is real.
+
+``caution``
+===========
+
+.. caution::
+
+   Cliff ahead: Don't drive off it.
+
+``danger``
+==========
+
+.. danger::
+
+   Mad scientist at work!
+
+``error``
+=========
+
+.. error::
+
+   Does not compute.
+
+``hint``
+========
+
+.. hint::
+
+   Insulators insulate, until they are subject to ______ voltage.
+
+``important``
+=============
+
+.. important::
+
+   Tech is not neutral, nor is it apolitical.
+
+``note``
+========
+
+.. note::
+
+   This is a note.
+
+``seealso``
+===========
+
+.. seealso::
+
+   Other relevant information.
+
+``tip``
+=======
+
+.. tip::
+
+   25% if the service is good.
+
+``todo``
+========
+
+.. todo::
+
+   This needs the ``sphinx.ext.todo`` extension.
+
+``warning``
+===========
+
+.. warning::
+
+   Reader discretion is strongly advised.
+
+``versionadded``
+================
+
+.. versionadded:: v0.1.1
+
+   Here's a version added message.
+
+``versionchanged``
+==================
+
+.. versionchanged:: v0.1.1
+
+   Here's a version changed message.
+
+``deprecated``
+==============
+
+.. deprecated:: v0.1.1
+
+   Here's a deprecation message.