Merge ~jugmac00/lpci:start-sphinx-documentation into lpci:main

[Jürgen Gmach]

Start sphinx documentation

[Jürgen Gmach (jugmac00)]

see https://ibb.co/9ypHjqJ

[Jürgen Gmach (jugmac00)]

The readthedocs project can only be created/run successfully after this MP got merged.

[Colin Watson (cjwatson)]

review: Approve

diff --git a/.gitignore b/.gitignore
index 94df19c..903613f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,4 @@ __pycache__
 .coverage
 htmlcov
 build/
+docs/_build/
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
new file mode 100644
index 0000000..ead4dcd
--- /dev/null
+++ b/CONTRIBUTING.rst
@@ -0,0 +1,19 @@
+Developing
+==========
+
+To run this project's tests, use `tox <https://tox.readthedocs.io/en/latest/>`_.
+
+To update the `project's documentation
+<https://lpcraft.readthedocs.io/en/latest/>`_ you need to trigger a manual
+build on the project's dashboard on https://readthedocs.org.
+
+If you need to modify ``requirements.in``, run ``tox -e pip-compile``
+afterwards to regenerate ``requirements.txt``.
+
+
+Getting help
+------------
+
+If you find bugs in this package, you can report them here:
+
+    https://launchpad.net/lpcraft
diff --git a/README.rst b/README.rst
index 1e4f4e2..aa700b3 100644
--- a/README.rst
+++ b/README.rst
@@ -25,11 +25,3 @@ although it won't do very much useful yet.
 
 To save the output from a job, use ``lpcraft run --output
 /path/to/output/directory``.
-
-Developing
-==========
-
-Run tests using ``tox``.
-
-If you need to modify ``requirements.in``, run ``tox -e pip-compile``
-afterwards.
diff --git a/docs/CONTRIBUTING.rst b/docs/CONTRIBUTING.rst
new file mode 120000
index 0000000..798f2aa
--- /dev/null
+++ b/docs/CONTRIBUTING.rst
@@ -0,0 +1 @@
+../CONTRIBUTING.rst
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..7943bc6
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,60 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "lpcraft"
+copyright = "2021, Canonical Ltd"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# 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", ".DS_Store"]
+
+
+# -- 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_static_path = ["_static"]
+
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    "**": [
+        "globaltoc.html",
+        "relations.html",  # needs 'show_related': True theme option to display
+        "searchbox.html",
+    ]
+}
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..48860fc
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,48 @@
+.. lpcraft documentation master file, created by
+   sphinx-quickstart on Tue Dec  7 12:44:23 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+lpcraft
+=======
+
+``lpcraft`` is a runner for continuous integration jobs in Launchpad.  It is
+intended mainly for use in Launchpad builders, but can also be installed and
+used locally on branches with a ``.launchpad.yaml`` file.
+
+This project owes a considerable amount to `snapcraft
+<https://github.com/snapcore/snapcraft>`_ and `charmcraft
+<https://github.com/canonical/charmcraft>`_: the provider support for
+container management is based substantially on ``charmcraft``, while much of
+the CLI design is based on both those tools.
+
+The development is in a very early stage.
+
+Example configuration
+---------------------
+
+.. code:: bash
+
+    $ cat .launchpad.yaml
+    pipeline:
+    - test
+
+    jobs:
+        test:
+            series: focal
+            architectures: amd64
+            run: echo hello world >output
+            output:
+                paths: [output]
+
+    $ lpcraft run --output out
+    Running the job
+    $ cat out/test/focal/amd64/files/output
+    hello world
+
+
+.. toctree::
+    :maxdepth: 2
+
+    self
+    CONTRIBUTING
diff --git a/setup.cfg b/setup.cfg
index a1a9ef9..7f9e2d8 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -34,6 +34,8 @@ console_scripts =
     lpcraft = lpcraft.main:main
 
 [options.extras_require]
+docs =
+    sphinx
 test =
     coverage
     fixtures
diff --git a/tox.ini b/tox.ini
index 3e16570..7ee20e8 100644
--- a/tox.ini
+++ b/tox.ini
@@ -52,3 +52,9 @@ commands =
     coverage run -m pytest
     coverage html
     coverage report -m  --fail-under=100
+
+[testenv:docs]
+basepython = python3
+extras = docs
+commands =
+    sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html