Add skeleton documentation site files

welchbj · Aug 8, 2020 · 7a2c94c · 7a2c94c
1 parent 766f3fc
commit 7a2c94c
Show file tree

Hide file tree

Showing 32 changed files with 239 additions and 37 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,9 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  version: 3.8
+  install:
+    - requirements: deps/dev-requirements.txt
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <p align="center">
-  <img width="600" height="162" src="https://github.com/welchbj/almanac/blob/master/static/logo.png?raw=true" alt="almanac logo">
+  <img width="600" height="162" src="https://github.com/welchbj/almanac/blob/master/docs/_static/logo.png?raw=true" alt="almanac logo">
 </p>
 <p align="center">
   <em>a framework for interactive, page-based console applications</em>

diff --git a/deps/dev-requirements.txt b/deps/dev-requirements.txt
@@ -1,4 +1,5 @@
 flake8==3.8.3
+livereload==2.6.2
 mccabe==0.6.1
 munch==2.5.0
 mypy==0.782
@@ -9,6 +10,9 @@ pyflakes==2.2.0
 Pygments==2.6.1
 pyparsing==2.4.7
 readme_renderer[md]==26.0
+Sphinx==3.1.2
+sphinx-autodoc-typehints==1.11.0
+sphinx-rtd-theme==0.5.0
 twine==3.2.0
 typed-ast==1.4.1
 typing-extensions==3.7.4.2

diff --git a/static/logo.png → docs/_static/logo.png b/static/logo.png → docs/_static/logo.png
diff --git a/docs/api/arguments.rst b/docs/api/arguments.rst
@@ -0,0 +1,8 @@
+``almanac.arguments``
+=====================
+
+.. autoclass:: almanac.arguments.ArgumentBase
+
+.. autoclass:: almanac.arguments.FrozenArgument
+
+.. autoclass:: almanac.arguments.MutableArgument
diff --git a/docs/api/commands.rst b/docs/api/commands.rst
@@ -0,0 +1,8 @@
+``almanac.commands``
+====================
+
+.. autoclass:: almanac.commands.CommandBase
+
+.. autoclass:: almanac.commands.FrozenCommand
+
+.. autoclass:: almanac.commands.MutableCommand
diff --git a/docs/api/completion.rst b/docs/api/completion.rst
@@ -0,0 +1,8 @@
+``almanac.completion``
+======================
+
+.. autofunction:: almanac.completion.rewrite_completion_stream
+
+.. autoclass:: almanac.completion.PagePathCompleter
+
+.. autoclass:: almanac.completion.WordCompleter
diff --git a/docs/api/constants.rst b/docs/api/constants.rst
@@ -0,0 +1,4 @@
+``almanac.constants``
+=====================
+
+TODO
diff --git a/docs/api/context.rst b/docs/api/context.rst
@@ -0,0 +1,4 @@
+``almanac.context``
+===================
+
+TODO
diff --git a/docs/api/core.rst b/docs/api/core.rst
@@ -0,0 +1,4 @@
+``almanac.core``
+================
+
+TODO
diff --git a/docs/api/errors.rst b/docs/api/errors.rst
@@ -0,0 +1,4 @@
+``almanac.errors``
+==================
+
+TODO
diff --git a/docs/api/hooks.rst b/docs/api/hooks.rst
@@ -0,0 +1,4 @@
+``almanac.hooks``
+=================
+
+TODO
diff --git a/docs/api/io.rst b/docs/api/io.rst
@@ -0,0 +1,4 @@
+``almanac.io``
+=================
+
+TODO
diff --git a/docs/api/pages.rst b/docs/api/pages.rst
@@ -0,0 +1,4 @@
+``almanac.pages``
+=================
+
+TODO
diff --git a/docs/api/parsing.rst b/docs/api/parsing.rst
@@ -0,0 +1,4 @@
+``almanac.parsing``
+===================
+
+TODO
diff --git a/docs/api/shortcuts.rst b/docs/api/shortcuts.rst
@@ -0,0 +1,4 @@
+``almanac.shortcuts``
+=====================
+
+TODO
diff --git a/docs/api/style.rst b/docs/api/style.rst
@@ -0,0 +1,4 @@
+``almanac.styles``
+==================
+
+TODO
diff --git a/docs/api/types.rst b/docs/api/types.rst
@@ -0,0 +1,4 @@
+``almanac.types``
+=================
+
+TODO
diff --git a/docs/api/utils.rst b/docs/api/utils.rst
@@ -0,0 +1,4 @@
+``almanac.utils``
+=================
+
+TODO
diff --git a/docs/conf.py b/docs/conf.py
@@ -4,8 +4,7 @@
 import os
 import sys
 
-from datetime import (
-    datetime)
+from datetime import datetime
 
 # -- Path setup --------------------------------------------------------------
 
@@ -25,8 +24,11 @@
 author = 'Brian Welch'
 year = datetime.now().year
 copyright = f'{year}, {author}'
+
 version = '.'.join(str(i) for i in __version_info__[:2])  # noqa
 release = __version__  # noqa
+
+language = 'en'
 master_doc = 'index'
 source_suffix = '.rst'
 pygments_style = 'sphinx'
@@ -42,29 +44,30 @@
     'sphinx.ext.napoleon',
     'sphinx_autodoc_typehints',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.viewcode'
+    'sphinx.ext.viewcode',
+    'sphinx_rtd_theme'
 ]
 
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'prompt_toolkit': ('https://python-prompt-toolkit.readthedocs.io/en/master/', None)
+}
 
-autodoc_default_flags = [
-    'members',
-    'special-members',
-    'show-inheritance'
-]
+autodoc_default_options = {
+    'members': True,
+    'show-inheritance': True
+}
+
+napoleon_use_param = True
 
 suppress_warnings = [
     'image.nonlocal_uri'
 ]
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = [
     '_templates'
 ]
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
     '_build',
     'Thumbs.db',
@@ -74,14 +77,16 @@
 
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = 'alabaster'
-
-# 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,
-# so a file named "default.css" will overwrite the builtin "default.css".
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'canonical_url': 'https://almanac.brianwel.ch/',
+    'logo_only': True
+}
+html_title = f'almanac ({version})'
 html_static_path = [
-    '_static'
+    '_static',
 ]
+html_logo = '_static/logo.png'
+
+# TODO
+# html_favicon = 'TODO'
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,20 +1,58 @@
-.. almanac documentation master file, created by
-   sphinx-quickstart on Sun Jun  9 14:50:36 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+=============
+Welcome to...
+=============
 
-Welcome to almanac's documentation!
-===================================
+.. raw:: html
+
+  <p align="center">
+    <img width="600" height="162" src="https://github.com/welchbj/almanac/blob/master/static/logo.png?raw=true" alt="almanac logo">
+  </p>
+  <p align="center">
+    <em>a framework for interactive, page-based console applications</em>
+  </p>
+  <p align="center">
+    <a href="https://travis-ci.org/welchbj/almanac">
+      <img src="https://img.shields.io/travis/welchbj/almanac/devel.svg?style=flat-square&label=linux%20build" alt="linux build status">
+    </a>
+    <a href="https://ci.appveyor.com/project/welchbj/almanac">
+      <img src="https://img.shields.io/appveyor/ci/welchbj/almanac/devel.svg?style=flat-square&label=windows%20build" alt="windows build status">
+    </a>
+    <a href="https://pypi.org/project/almanac/">
+      <img src="https://img.shields.io/pypi/v/almanac.svg?style=flat-square&label=pypi" alt="pypi">
+    </a>
+    <a href="https://www.python.org/">
+      <img src="https://img.shields.io/badge/python-3.8+-b042f4.svg?style=flat-square" alt="python version">
+    </a>
+  </p>
+
+-----
+
+.. warning::
+
+    ``almanac`` is heavily tested and fully usable, but is still pre-1.0/stable software with **no guarantees** of avoiding breaking API changes until hitting version 1.0.
 
 .. toctree::
+   :caption: User Guide
    :maxdepth: 2
-   :caption: Contents:
 
+   user_guide/quick_start.rst
+   user_guide/commands_and_arguments.rst
+   user_guide/hooks.rst
+   user_guide/promoters.rst
+   user_guide/styling.rst
 
+.. toctree::
+   :caption: Project Meta
+   :maxdepth: 1
+   :glob:
+
+   project_meta/release_notes.rst
+   project_meta/development_guide.rst
+   project_meta/contributors.rst
+   project_meta/prior_art.rst
 
-Indices and tables
-==================
+.. toctree::
+   :caption: API Reference
+   :glob:
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   api/*
diff --git a/docs/project_meta/contributors.rst b/docs/project_meta/contributors.rst
@@ -0,0 +1,4 @@
+Contributors
+============
+
+TODO
diff --git a/docs/project_meta/development_guide.rst b/docs/project_meta/development_guide.rst
@@ -0,0 +1,4 @@
+Development Guide
+=================
+
+TODO
diff --git a/docs/project_meta/prior_art.rst b/docs/project_meta/prior_art.rst
@@ -0,0 +1,4 @@
+Prior Art
+=========
+
+TODO
diff --git a/docs/project_meta/release_notes.rst b/docs/project_meta/release_notes.rst
@@ -0,0 +1,4 @@
+Release Notes
+=============
+
+TODO
diff --git a/docs/user_guide/commands_and_arguments.rst b/docs/user_guide/commands_and_arguments.rst
@@ -0,0 +1,4 @@
+Commands and Arguments
+======================
+
+TODO
diff --git a/docs/user_guide/hooks.rst b/docs/user_guide/hooks.rst
@@ -0,0 +1,4 @@
+Hooks
+=====
+
+TODO
diff --git a/docs/user_guide/promoters.rst b/docs/user_guide/promoters.rst
@@ -0,0 +1,4 @@
+Promoters
+=========
+
+TODO
diff --git a/docs/user_guide/quick_start.rst b/docs/user_guide/quick_start.rst
@@ -0,0 +1,4 @@
+Quick Start
+===========
+
+TODO
diff --git a/docs/user_guide/styling.rst b/docs/user_guide/styling.rst
@@ -0,0 +1,4 @@
+Styling
+=======
+
+TODO
diff --git a/examples/http_client_from_readme.py b/examples/http_client_from_readme.py
@@ -7,7 +7,7 @@
 #
 # Install dependencies with:
 #
-# pip install almanac aiohttp pygments
+# pip install almanac aiohttp
 #
 
 import aiohttp