Jürgen Gmach has proposed merging ~jugmac00/lpcraft:start-sphinx-documentation into lpcraft:main.
Commit message: Start sphinx documentation Requested reviews: Launchpad code reviewers (launchpad-reviewers) For more details, see: https://code.launchpad.net/~jugmac00/lpcraft/+git/lpcraft/+merge/412854 -- Your team Launchpad code reviewers is requested to review the proposed merge of ~jugmac00/lpcraft:start-sphinx-documentation into lpcraft:main.
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
_______________________________________________ Mailing list: https://launchpad.net/~launchpad-reviewers Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-reviewers More help : https://help.launchpad.net/ListHelp
