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
_______________________________________________ Mailing list: https://launchpad.net/~launchpad-reviewers Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-reviewers More help : https://help.launchpad.net/ListHelp
