Merge pull request #100 from tmbo/kiancross-add-docs

Random docs changes

.github/workflows/continous-integration.yml

@@ -116,9 +116,7 @@ jobs:
       uses: Gr1N/setup-poetry@v4
 
     - name: Install dependencies 🖥
-      run: |
-        poetry install --no-interaction
-        pip install -r docs/source/requirements.txt
+      run: poetry install --no-interaction --extras "docs"
 
     - name: Build docs ⚒️
       run: make docs

.readthedocs.yml

@@ -12,6 +12,7 @@ sphinx:
 python:
   version: 3.7
   install:
-    - requirements: docs/source/requirements.txt
     - method: pip
       path: .
+      extra_requirements:
+        - docs

Makefile

@@ -1,4 +1,4 @@
-.PHONY: clean install formatter lint test types docs
+.PHONY: clean install formatter lint test types docs livedocs
 
 JOBS ?= 1
 
@@ -18,6 +18,8 @@ help:
 	@echo "        Check for type errors using pytype."
 	@echo "    docs"
 	@echo "        Build the documentation."
+	@echo "    livedocs"
+	@echo "        Build the documentation with a live preview for quick iteration."
 
 clean:
 	find . -name '*.pyc' -exec rm -f {} +
@@ -45,4 +47,7 @@ types:
 	poetry run mypy questionary
 
 docs:
-	make -C docs html
+	poetry run make -C docs html
+
+livedocs:
+	poetry run sphinx-autobuild docs docs/build/html

README.md

@@ -3,9 +3,9 @@
 [![Version](https://img.shields.io/pypi/v/questionary.svg)](https://pypi.org/project/questionary/)
 [![License](https://img.shields.io/pypi/l/questionary.svg)](#)
 [![Continuous Integration](https://github.com/tmbo/questionary/workflows/Continuous%20Integration/badge.svg)](#)
-[![Coverage Status](https://coveralls.io/repos/github/tmbo/questionary/badge.svg?branch=master)](https://coveralls.io/github/tmbo/questionary?branch=master)
+[![Coverage](https://coveralls.io/repos/github/tmbo/questionary/badge.svg?branch=master)](https://coveralls.io/github/tmbo/questionary?branch=master)
 [![Supported Python Versions](https://img.shields.io/pypi/pyversions/questionary.svg)](https://pypi.python.org/pypi/questionary)
-[![Documentation Status](https://readthedocs.org/projects/questionary/badge/?version=latest)](https://questionary.readthedocs.io/en/latest/?badge=latest)
+[![Documentation](https://readthedocs.org/projects/questionary/badge/?version=latest)](https://questionary.readthedocs.io/en/latest/?badge=latest)
 
 ✨ Questionary is a Python library for effortlessly building pretty command line interfaces ✨
 

docs/Makefile

@@ -4,14 +4,14 @@
 # You can set these variables from the command line.
 SPHINXOPTS    = -W --keep-going -n
 SPHINXBUILD   = sphinx-build
-SOURCEDIR     = source
+SOURCEDIR     = .
 BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help github Makefile
+.PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/conf.py

@@ -0,0 +1,90 @@
+import json
+import os
+import sys
+import traceback
+
+sys.path.insert(0, os.path.abspath("../"))
+from questionary import __version__
+
+project = "Questionary"
+copyright = "2020, Questionary"
+author = "Questionary"
+
+version = __version__
+release = __version__
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+    "sphinx_autodoc_typehints",
+]
+
+nitpick_ignore = [
+    ("py:class", "questionary.prompts.common.Choice"),
+    ("py:class", "questionary.question.Question"),
+    ("py:class", "questionary.form.Form"),
+]
+
+autodoc_typehints = "description"
+
+copybutton_prompt_text = r">>> |\.\.\. |\$ "
+copybutton_prompt_is_regexp = True
+
+html_theme = "sphinx_rtd_theme"
+
+html_theme_options = {
+    "navigation_depth": 2,
+}
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "prompt_toolkit": ("https://python-prompt-toolkit.readthedocs.io/en/master/", None),
+}
+
+autodoc_member_order = "alphabetical"
+
+# TODO: remove as soon as we upgrade to sphinx 4.0
+# Borrowed from https://github.com/sphinx-doc/sphinx/issues/5603
+intersphinx_aliases = {
+    ("py:class", "prompt_toolkit.styles.style.Style"): (
+        "py:class",
+        "prompt_toolkit.styles.Style",
+    ),
+    ("py:class", "prompt_toolkit.shortcuts.prompt.CompleteStyle"): (
+        "py:class",
+        "prompt_toolkit.shortcuts.CompleteStyle",
+    ),
+    ("py:class", "prompt_toolkit.completion.base.Completer"): (
+        "py:class",
+        "prompt_toolkit.completion.Completer",
+    ),
+    ("py:class", "prompt_toolkit.lexers.base.Lexer"): (
+        "py:class",
+        "prompt_toolkit.lexers.Lexer",
+    ),
+}
+
+
+def add_intersphinx_aliases_to_inv(app):
+    from sphinx.ext.intersphinx import InventoryAdapter
+
+    inventories = InventoryAdapter(app.builder.env)
+
+    for alias, target in app.config.intersphinx_aliases.items():
+        alias_domain, alias_name = alias
+        target_domain, target_name = target
+
+        try:
+            found = inventories.main_inventory[target_domain][target_name]
+            inventories.main_inventory[alias_domain][alias_name] = found
+        except KeyError as e:
+            traceback.print_exc()
+            continue
+
+
+def setup(app):
+    app.add_config_value("intersphinx_aliases", {}, "env")
+    app.connect("builder-inited", add_intersphinx_aliases_to_inv)

docs/index.rst

@@ -0,0 +1,67 @@
+***********
+Questionary
+***********
+
+.. image:: https://img.shields.io/pypi/v/questionary.svg
+  :target: https://pypi.org/project/questionary/
+  :alt: Version
+
+.. image:: https://img.shields.io/pypi/l/questionary.svg
+  :target: #
+  :alt: License
+
+.. image:: https://img.shields.io/pypi/pyversions/questionary.svg
+  :target: https://pypi.python.org/pypi/questionary
+  :alt: Supported Python Versions
+
+✨ Questionary is a Python library for effortlessly building pretty command line interfaces ✨
+
+It makes it very easy to query your user for input. You need your user to
+confirm a destructive action or enter a file path? We've got you covered:
+
+.. image:: images/example.gif
+
+Creating your first prompt is just a few key strokes away
+
+.. code-block:: python3
+
+  import questionary
+
+  first_name = questionary.text("What's your first name").ask()
+
+This prompt will ask the user to provide free text input and the result is
+stored in ``first_name``.
+
+You can install Questionary using pip (for details, head over to the :ref:`installation` page):
+
+.. code-block:: console
+
+  $ pip install questionary
+
+Ready to go? Check out the :ref:`quickstart`.
+
+License
+=======
+Licensed under the `MIT License <https://github.com/tmbo/questionary/blob/master/LICENSE>`_.
+Copyright 2020 Tom Bocklisch.
+
+.. toctree::
+   :hidden:
+
+   pages/installation
+   pages/quickstart
+   pages/types
+   pages/advanced
+   pages/api_reference
+   pages/support
+   Examples <https://github.com/tmbo/questionary/tree/master/examples>
+
+.. toctree::
+   :hidden:
+
+   pages/contributors
+
+.. toctree::
+   :hidden:
+
+   pages/release_history