launchpad-reviewers team mailing list archive

[Jürgen Gmach <mp+415217@xxxxxxxxxxxxxxxxxx>]

Jürgen Gmach has proposed merging ~jugmac00/launchpad-buildd:publish-documentation-on-rtd into launchpad-buildd:master.

Commit message:
Publish documentation on Read the Docs

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~jugmac00/launchpad-buildd/+git/launchpad-buildd/+merge/415217
-- 
Your team Launchpad code reviewers is requested to review the proposed merge of ~jugmac00/launchpad-buildd:publish-documentation-on-rtd into launchpad-buildd:master.

diff --git a/.gitignore b/.gitignore
index cd48f47..ef4c204 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,3 +14,5 @@ debian/tmp
 debian/*.debhelper.log
 debian/*.debhelper
 debian/*.substvars
+.tox/
+docs/_build/
diff --git a/README b/README
deleted file mode 100644
index f8b0407..0000000
--- a/README
+++ /dev/null
@@ -1,78 +0,0 @@
-****************
-launchpad-buildd
-****************
-
-This project is the build daemon used by Launchpad's package-building
-infrastructure.
-
-It is licensed under the GNU Affero General Public Licence, version 3 (see the
-file LICENCE) except for some files originating elsewhere, which are marked
-with the licence that applies.
-
-See https://dev.launchpad.net/ for more context.
-
-----
-
-In order to build the package you need dpkg-dev and fakeroot
-
-To build the package do:
-
-debian/rules package
-dpkg-buildpackage -rfakeroot -b
-
-It will "fail" because the package built in the "wrong" place. Don't
-worry about that.
-
-To clean up, do:
-
-fakeroot debian/rules clean
-rm launchpad-buildd*deb
-rm ../launchpad-buildd*changes
-
-
-Developing
-************
-
-First of all, it is recommended that you create a lxc container, since the
-following steps will make changes in your system. And since some build types
-will only work with virtualized containers, creating a lxc vm is the best way
-to go. You can create a container with the following command:
-
-        lxc launch --vm ubuntu:18.04 lp-builddev
-
-Note that you may want to have a profile to share the source code with the
-container before running the above command.
-
-Then, inside the container, install the necessary dependencies:
-
-        sudo apt-get update
-        cat system-dependencies.txt | sudo xargs apt-get install -y
-
-This should be enough for you to be able to run `make check`, which runs the
-test suite both in python2 and python3.
-
-More information on how to integrate it with Launchpad can be found here:
-https://dev.launchpad.net/Soyuz/HowToDevelopWithBuildd
-
-Now, happy coding.
-
-
-Production deployment notes
-***************************
-
-In Launchpad's production build farm, launchpad-buildd is deployed via base
-virtual machine images constructed by taking standard Ubuntu cloud images
-and installing launchpad-buildd in them from
-https://launchpad.net/~canonical-is-sa/+archive/ubuntu/buildd.  This is done
-by
-https://code.launchpad.net/~canonical-sysadmins/canonical-is-charms/launchpad-buildd-image-modifier
-(currently private, sorry).
-
-At present (November 2020), most of these base VM images are built from
-Ubuntu bionic, and launchpad-buildd runs on Python 3.  However, it's
-necessary to support the powerpc architecture until at least April 2021 (end
-of standard maintenance for xenial), and the powerpc base images need to
-stay on xenial since that architecture is no longer supported by bionic;
-furthermore, the version of Twisted in xenial has some bugs that break
-launchpad-buildd when running on Python 3.  As a result, launchpad-buildd
-must run on both Python 2 and 3 for the time being.
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..8cadaf3
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,15 @@
+****************
+launchpad-buildd
+****************
+
+This project is the build daemon used by Launchpad's package-building
+infrastructure.
+
+It is licensed under the GNU Affero General Public Licence, version 3 (see the
+file LICENCE) except for some files originating elsewhere, which are marked
+with the licence that applies.
+
+See https://dev.launchpad.net/ for more context.
+
+The documentation is available at
+https://launchpad-buildd.readthedocs.io/en/latest/
diff --git a/docs/building.rst b/docs/building.rst
new file mode 100644
index 0000000..4893bb8
--- /dev/null
+++ b/docs/building.rst
@@ -0,0 +1,22 @@
+Building the project
+********************
+
+In order to build the package you need ``dpkg-dev`` and ``fakeroot``.
+
+To build the package, do:
+
+.. code:: bash
+
+    debian/rules package
+    dpkg-buildpackage -rfakeroot -b
+
+It will "fail" because the package built in the "wrong" place.
+Don't worry about that.
+
+To clean up, do:
+
+.. code:: bash
+
+    fakeroot debian/rules clean
+    rm launchpad-buildd*deb
+    rm ../launchpad-buildd*changes
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..049f6df
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,65 @@
+# 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 = 'launchpad-buildd'
+copyright = '2022, Canonical Ltd'
+author = 'Launchpad developers'
+
+# The full version, including alpha/beta/rc tags
+release = '207'
+
+
+# -- 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 = []
+
+# 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/deployment.rst b/docs/deployment.rst
new file mode 100644
index 0000000..19b5fef
--- /dev/null
+++ b/docs/deployment.rst
@@ -0,0 +1,19 @@
+Production deployment notes
+***************************
+
+In Launchpad's production build farm, launchpad-buildd is deployed via base
+virtual machine images constructed by taking standard Ubuntu cloud images
+and installing launchpad-buildd in them from
+https://launchpad.net/~canonical-is-sa/+archive/ubuntu/buildd.  This is done
+by
+https://code.launchpad.net/~canonical-sysadmins/canonical-is-charms/launchpad-buildd-image-modifier
+(currently private, sorry).
+
+At present (November 2020), most of these base VM images are built from
+Ubuntu bionic, and launchpad-buildd runs on Python 3.  However, it's
+necessary to support the powerpc architecture until at least April 2021 (end
+of standard maintenance for xenial), and the powerpc base images need to
+stay on xenial since that architecture is no longer supported by bionic;
+furthermore, the version of Twisted in xenial has some bugs that break
+launchpad-buildd when running on Python 3.  As a result, launchpad-buildd
+must run on both Python 2 and 3 for the time being.
\ No newline at end of file
diff --git a/docs/developing.rst b/docs/developing.rst
new file mode 100644
index 0000000..77a626c
--- /dev/null
+++ b/docs/developing.rst
@@ -0,0 +1,41 @@
+Developing
+**********
+
+First of all, it is recommended that you create an lxc container, since the
+following steps will make changes in your system. And since some build types
+will only work with virtualized containers, creating an lxc vm is the best way
+to go. If you just want to run the test suite, creating a container is
+sufficient.
+
+You can create a container with the following command:
+
+.. code:: bash
+
+        lxc launch --vm ubuntu:18.04 lp-builddev
+
+Note that you may want to have a profile to share the source code with the
+container before running the above command.
+
+Then, inside the container, install the necessary dependencies:
+
+.. code:: bash
+
+        sudo apt-get update
+        cat system-dependencies.txt | sudo xargs apt-get install -y
+
+This should be enough for you to be able to run `make check`, which runs the
+test suite both in python2 and python3.
+
+More information on how to integrate it with Launchpad can be found here:
+https://dev.launchpad.net/Soyuz/HowToDevelopWithBuildd
+
+
+Creating a changelog entry
+--------------------------
+
+In order to create a changelog entry in ``debian/changelog``,
+you need to run ``dch`` from the ``devscripts`` package.
+
+.. code:: bash
+
+    dch
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..427c800
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,25 @@
+.. launchpad-buildd documentation master file, created by
+   sphinx-quickstart on Mon Feb  7 17:54:05 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+launchpad-buildd
+================
+
+This project is the build daemon used by Launchpad's package-building
+infrastructure.
+
+It is licensed under the GNU Affero General Public Licence, version 3 (see the
+file LICENCE) except for some files originating elsewhere, which are marked
+with the licence that applies.
+
+See https://dev.launchpad.net/ for more context.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   self
+   developing
+   building
+   deployment
diff --git a/setup.py b/setup.py
index aa05864..23ec786 100755
--- a/setup.py
+++ b/setup.py
@@ -66,6 +66,7 @@ setup(
         ],
     extras_require={
         'lxd': ['netaddr', 'pylxd'],
+        'docs': ['sphinx'],
         },
     test_suite='lpbuildd',
     tests_require=[
diff --git a/tox.ini b/tox.ini
new file mode 100644
index 0000000..4f38868
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,9 @@
+[tox]
+env_list = docs
+
+[testenv:docs]
+description = Build documentation via Sphinx.
+basepython = python3
+extras = docs
+commands =
+    sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html