Commit 055b77e8 authored by Tristan Van Berkom's avatar Tristan Van Berkom

doc: Added plugins as ToC elements instead of orphaned links

  o Now the page titles are declared in plugins, allowing for
    a more descriptive ToC

  o Makefile and plugin.rsttemplate updated to not produce the title,
    to no longer use `:orphan:` for plugin pages, and to ignore any
    private modules in the plugin directories.

  o Interestingly, now the docs will fail to build if you add
    a new plugin and forget to add it to the documentation.
parent 71b78794
......@@ -18,8 +18,9 @@
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""Autotools build element
"""
autotools - Autotools build element
===================================
This is a :mod:`BuildElement <buildstream.buildelement>` implementation for
using Autotools build scripts (also known as the `GNU Build System
<https://en.wikipedia.org/wiki/GNU_Build_System>`_).
......
......@@ -18,8 +18,9 @@
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""CMake build element
"""
cmake - CMake build element
===========================
This is a :mod:`BuildElement <buildstream.buildelement>` implementation for
using the `CMake <https://cmake.org/>`_ build system.
......
......@@ -18,8 +18,9 @@
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""Compose element
"""
compose - Compose the output of multiple elements
=================================================
This element creates a selective composition of its dependencies.
This is normally used at near the end of a pipeline to prepare
......
......@@ -18,8 +18,9 @@
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""Python Distutils element
"""
distutils - Python distutils element
====================================
A :mod:`BuildElement <buildstream.buildelement>` implementation for using
python distutils
......
......@@ -18,8 +18,9 @@
# Authors:
# Jonathan Maw <jonathan.maw@codethink.co.uk>
"""Filter element
"""
filter - Extract a subset of files from another element
=======================================================
This filters another element by producing an output that is a subset of
the filtered element.
......
......@@ -18,8 +18,9 @@
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""Import element
"""
import - Import sources directly
================================
Import elements produce artifacts directly from its sources
without any kind of processing. These are typically used to
import an SDK to build on top of or to overlay your build with
......
......@@ -18,8 +18,9 @@
# Authors:
# Jürg Billeter <juerg.billeter@codethink.co.uk>
"""Junction element
"""
junction - Integrate subprojects
================================
This element is a link to another BuildStream project. It allows integration
of multiple projects into a single pipeline.
......
......@@ -18,8 +18,9 @@
# Authors:
# Ed Baunton <ebaunton1@bloomberg.net>
"""Make build element
"""
make - Make build element
=========================
This is a :mod:`BuildElement <buildstream.buildelement>` implementation for
using GNU make based build.
......
......@@ -18,8 +18,9 @@
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""Perl MakeMaker build element
"""
makemaker - Perl MakeMaker build element
========================================
A :mod:`BuildElement <buildstream.buildelement>` implementation for using
the Perl ExtUtil::MakeMaker build system
......
......@@ -18,8 +18,9 @@
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""Manual build element
"""
manual - Manual build element
=============================
The most basic build element does nothing but allows users to
add custom build commands to the array understood by the :mod:`BuildElement <buildstream.buildelement>`
......
......@@ -14,8 +14,9 @@
# You should have received a copy of the GNU Lesser General Public
# License along with this library. If not, see <http://www.gnu.org/licenses/>.
"""Meson build element
"""
meson - Meson build element
===========================
This is a :mod:`BuildElement <buildstream.buildelement>` implementation for
using `Meson <http://mesonbuild.com/>`_ build scripts.
......
......@@ -18,8 +18,9 @@
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""Perl Module::Build build element
"""
modulebuild - Perl Module::Build build element
==============================================
A :mod:`BuildElement <buildstream.buildelement>` implementation for using
the Perl Module::Build build system
......
......@@ -18,8 +18,9 @@
# Authors:
# Mathieu Bridon <bochecha@daitauha.fr>
"""Pip build element
"""
pip - Pip build element
=======================
A :mod:`BuildElement <buildstream.buildelement>` implementation for installing
Python modules with pip
......
......@@ -18,8 +18,9 @@
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""CMake build element
"""
qmake - QMake build element
===========================
A :mod:`BuildElement <buildstream.buildelement>` implementation for using
the qmake build system
......
......@@ -19,8 +19,9 @@
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
# Jonathan Maw <jonathan.maw@codethink.co.uk>
"""Script element
"""
script - Run scripts to create output
=====================================
This element allows one to run some commands to mutate the
input and create some output.
......
......@@ -18,8 +18,9 @@
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""Stack element
"""
stack - Symbolic Element for dependency grouping
================================================
Stack elements are simply a symbolic element used for representing
a logical group of elements.
"""
......
......@@ -17,7 +17,9 @@
# Authors:
# Jonathan Maw <jonathan.maw@codethink.co.uk>
"""A source implementation for staging bazaar branches
"""
bzr - stage files from a bazaar repository
==========================================
**Usage:**
......
......@@ -19,7 +19,9 @@
# Jonathan Maw <jonathan.maw@codethink.co.uk>
# Richard Maw <richard.maw@codethink.co.uk>
"""A source implementation for staging deb files
"""
deb - stage files from .deb packages
====================================
**Usage:**
......
......@@ -18,7 +18,9 @@
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""A Source implementation for staging git checkouts
"""
git - stage files from a git repository
=======================================
**Usage:**
......
......@@ -18,7 +18,9 @@
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""A Source implementation for staging local project files
"""
local - stage local files and directories
=========================================
**Usage:**
......
......@@ -18,7 +18,9 @@
# Authors:
# Andrew Leeming <andrew.leeming@codethink.co.uk>
"""A Source implementation for importing/staging of OSTree checkouts.
"""
ostree - stage files from an OSTree repository
==============================================
**Usage:**
......
......@@ -18,7 +18,9 @@
# Authors:
# Chandan Singh <csingh43@bloomberg.net>
"""A Source implementation for applying local patches
"""
patch - apply locally stored patches
====================================
**Usage:**
......
#!/usr/bin/env python3
#
# Copyright (C) 2017 Codethink Limited
#
# This program is free software; you can redistribute it and/or
......@@ -17,7 +18,9 @@
# Authors:
# Jonathan Maw <jonathan.maw@codethink.co.uk>
"""A source implementation for staging tar files
"""
tar - stage files from tar archives
===================================
**Usage:**
......
......@@ -18,7 +18,9 @@
# Authors:
# Mathieu Bridon <bochecha@daitauha.fr>
"""A source implementation for staging zip files
"""
zip - stage files from zip archives
===================================
**Usage:**
......
......@@ -43,13 +43,12 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# from plugin documentation.
#
define plugin-doc-skeleton
@for file in $$(find ${1} -name "*.py" ! -name "__init__.py"); do \
@for file in $$(find ${1} -name "*.py" ! -name "_*.py"); do \
base=$$(basename $$file); \
module=${2}.$${base%.py}; \
modname=$${base%.py}; \
echo -n "Generating source/${2}/$${modname}.rst... "; \
sed -e "s|@@MODULENAME@@|$${modname}|g" \
-e "s|@@MODULE@@|$${module}|g" \
sed -e "s|@@MODULE@@|$${module}|g" \
source/plugin.rsttemplate > \
source/${2}/$${modname}.rst.tmp && \
mv source/${2}/$${modname}.rst.tmp source/${2}/$${modname}.rst || exit 1; \
......
......@@ -28,49 +28,49 @@ given element specify their plugin specific configuration directly
:ref:`in their source declarations <format_sources>`.
Elements
~~~~~~~~
The following element types are provided with BuildStream:
General elements
''''''''''''''''
~~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
* :mod:`stack <elements.stack>` - Symbolic Element for dependency grouping
* :mod:`import <elements.import>` - Import sources directly
* :mod:`compose <elements.compose>` - Compose the output of multiple elements
* :mod:`script <elements.script>` - Run scripts to create output
* :mod:`junction <elements.junction>` - Integrate subprojects
* :mod:`filter <elements.filter>` - Extract a subset of files from another element
elements/stack
elements/import
elements/compose
elements/script
elements/junction
elements/filter
Build elements
''''''''''''''
~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
* :mod:`manual <elements.manual>` - Manual Build Element
* :mod:`make <elements.make>` - Make Build Element
* :mod:`autotools <elements.autotools>` - Autotools Build Element
* :mod:`cmake <elements.cmake>` - CMake Build Element
* :mod:`qmake <elements.qmake>` - QMake Build Element
* :mod:`distutils <elements.distutils>` - Python Distutils Build Element
* :mod:`makemaker <elements.makemaker>` - Perl MakeMaker Build Element
* :mod:`modulebuild <elements.modulebuild>` - Perl Module::Build Build Element
* :mod:`meson <elements.meson>` - Meson Build Element
* :mod:`pip <elements.pip>` - Pip build element
elements/manual
elements/make
elements/autotools
elements/cmake
elements/qmake
elements/distutils
elements/makemaker
elements/modulebuild
elements/meson
elements/pip
Sources
~~~~~~~
The following source types are provided with BuildStream:
* :mod:`local <sources.local>` - A Source implementation for local files and directories
* :mod:`tar <sources.tar>` - A Source implementation for tarballs
* :mod:`zip <sources.zip>` - A Source implementation for zip archives
* :mod:`git <sources.git>` - A Source implementation for git
* :mod:`bzr <sources.bzr>` - A Source implementation for bazaar
* :mod:`ostree <sources.ostree>` - A Source implementation for ostree
* :mod:`patch <sources.patch>` - A Source implementation for applying local patches
* :mod:`deb <sources.deb>` - A Source implementation for deb packages
.. toctree::
:maxdepth: 1
sources/local
sources/tar
sources/zip
sources/git
sources/bzr
sources/ostree
sources/patch
sources/deb
External plugins
......
:orphan:
@@MODULENAME@@ plugin
============================================
.. automodule:: @@MODULE@@
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment