Commit cf32b669 authored by Darko Poljak's avatar Darko Poljak

Write sphinx rst docs.

parent 091ddac3
......@@ -20,6 +20,9 @@ MANIFEST
dist/
cdist/version.py
#sphinx build dir
_build/
# Packaging: Archlinux
/PKGBUILD
/cdist-*.pkg.tar.xz
......
......@@ -18,15 +18,6 @@
#
#
A2XM=a2x -f manpage --no-xmllint -a encoding=UTF-8
A2XH=a2x -f xhtml --no-xmllint -a encoding=UTF-8
# Create cross-links in html man pages
# We look for something like "cdist-type(7)" and make a href out of it
# The first matching group is the man page name and the second group
# is the man page section (1 or 7). The first three lines of the input
# (xml, DOCTYPE, head tags) are ignored, since the head tags contains
# the title of the page and should not contain a href.
CROSSLINK=sed -i '' '1,3!s/\([[:alnum:]_-]*\)(\([17]\))/<a href="..\/man\2\/\1.html">&<\/a>/g'
helper=./bin/build-helper
MANDIR=docs/man
......@@ -45,6 +36,8 @@ CHANGELOG_FILE=docs/changelog
PYTHON_VERSION=cdist/version.py
SPHINXM=make -C $(MANDIR) man
SPHINXH=make -C $(MANDIR) html
################################################################################
# Manpages
#
......@@ -52,59 +45,42 @@ MAN1DSTDIR=$(MANDIR)/man1
MAN7DSTDIR=$(MANDIR)/man7
# Manpages #1: Types
# Use shell / ls to get complete list - $(TYPEDIR)/*/man.text does not work
MANTYPESRC=$(shell ls $(TYPEDIR)/*/man.text)
# replace first path component
# Use shell / ls to get complete list - $(TYPEDIR)/*/man.rst does not work
MANTYPESRC=$(shell ls $(TYPEDIR)/*/man.rst)
MANTYPEPREFIX=$(subst $(TYPEDIR)/,$(MAN7DSTDIR)/cdist-type,$(MANTYPESRC))
MANTYPES=$(subst /man.rst,.rst,$(MANTYPEPREFIX))
# replace man.text with .7 or .html
MANTYPEMAN=$(subst /man.text,.7,$(MANTYPEPREFIX))
MANTYPEHTML=$(subst /man.text,.html,$(MANTYPEPREFIX))
MANTYPEALL=$(MANTYPEMAN) $(MANTYPEHTML)
# Link manpage so A2XH does not create man.html but correct named file
$(MAN7DSTDIR)/cdist-type%.text: $(TYPEDIR)/%/man.text
# Link manpage: do not create man.html but correct named file
$(MAN7DSTDIR)/cdist-type%.rst: $(TYPEDIR)/%/man.rst
ln -sf "../../../$^" $@
# Manpages #2: reference
MANREF=$(MAN7DSTDIR)/cdist-reference.text
MANREFSH=$(MANDIR)/cdist-reference.text.sh
MANREFMAN=$(MANREF:.text=.7)
MANREFHTML=$(MANREF:.text=.html)
MANREFALL=$(MANREFMAN) $(MANREFHTML)
MANREF=$(MAN7DSTDIR)/cdist-reference.rst
MANREFSH=$(MANDIR)/cdist-reference.rst.sh
$(MANREF): $(MANREFSH)
$(MANREFSH)
# Manpages #3: static pages
MAN1STATIC=$(shell ls $(MAN1DSTDIR)/*.text)
MAN7STATIC=$(shell ls $(MAN7DSTDIR)/*.text)
MANSTATICMAN=$(MAN1STATIC:.text=.1) $(MAN7STATIC:.text=.7)
MANSTATICHTML=$(MAN1STATIC:.text=.html) $(MAN7STATIC:.text=.html)
MANSTATICALL=$(MANSTATICMAN) $(MANSTATICHTML)
# Manpages #4: generic part
# Manpages #3: generic part
mansphinxman: $(MANTYPES) $(MANREF)
$(SPHINXM)
# Creating the type manpage
%.1 %.7: %.text
$(A2XM) $^
mansphinxhtml: $(MANTYPES) $(MANREF)
$(SPHINXH)
# Creating the type html page
%.html: %.text
$(A2XH) $^
$(CROSSLINK) $@
man: $(MANTYPEALL) $(MANREFALL) $(MANSTATICALL)
man: mansphinxman mansphinxhtml
# Manpages #5: release part
MANWEBDIR=$(WEBBASE)/man/$(CHANGELOG_VERSION)
MANBUILDDIR=$(MANDIR)/_build/html
man-dist: man check-date
man-dist: man
rm -rf "${MANWEBDIR}"
mkdir -p "${MANWEBDIR}/man1" "${MANWEBDIR}/man7"
cp ${MAN1DSTDIR}/*.html ${MAN1DSTDIR}/*.css ${MANWEBDIR}/man1
cp ${MAN7DSTDIR}/*.html ${MAN7DSTDIR}/*.css ${MANWEBDIR}/man7
mkdir -p "${MANWEBDIR}"
# mkdir -p "${MANWEBDIR}/man1" "${MANWEBDIR}/man7"
# cp ${MAN1DSTDIR}/*.html ${MAN1DSTDIR}/*.css ${MANWEBDIR}/man1
# cp ${MAN7DSTDIR}/*.html ${MAN7DSTDIR}/*.css ${MANWEBDIR}/man7
cp -R ${MANBUILDDIR}/* ${MANWEBDIR}
cd ${MANWEBDIR} && git add . && git commit -m "cdist manpages update: $(CHANGELOG_VERSION)" || true
man-latest-link: web-pub
......@@ -216,15 +192,13 @@ release:
#
clean:
rm -f $(MAN7DSTDIR)/cdist-reference.text
rm -f $(MAN7DSTDIR)/cdist-reference.rst
find "$(MANDIR)" -mindepth 2 -type l \
-o -name "*.1" \
-o -name "*.7" \
-o -name "*.html" \
-o -name "*.xml" \
| xargs rm -f
make -C $(MANDIR) clean
find * -name __pycache__ | xargs rm -rf
# Archlinux
......
cdist-type__apt_key(7)
======================
Steven Armstrong <steven-cdist--@--armstrong.cc>
Manage the list of keys used by apt
NAME
----
cdist-type__apt_key - manage the list of keys used by apt
Steven Armstrong <steven-cdist--@--armstrong.cc>
DESCRIPTION
......@@ -20,13 +17,13 @@ None.
OPTIONAL PARAMETERS
-------------------
state::
state
'present' or 'absent'. Defaults to 'present'
keyid::
keyid
the id of the key to add. Defaults to __object_id
keyserver::
keyserver
the keyserver from which to fetch the key. If omitted the default set in
./parameter/default/keyserver is used.
......@@ -34,25 +31,25 @@ keyserver::
EXAMPLES
--------
--------------------------------------------------------------------------------
# Add Ubuntu Archive Automatic Signing Key
__apt_key 437D05B5
# Same thing
__apt_key 437D05B5 --state present
# Get rid of it
__apt_key 437D05B5 --state absent
.. code-block:: sh
# Add Ubuntu Archive Automatic Signing Key
__apt_key 437D05B5
# Same thing
__apt_key 437D05B5 --state present
# Get rid of it
__apt_key 437D05B5 --state absent
# same thing with human readable name and explicit keyid
__apt_key UbuntuArchiveKey --keyid 437D05B5
# same thing with human readable name and explicit keyid
__apt_key UbuntuArchiveKey --keyid 437D05B5
# same thing with other keyserver
__apt_key UbuntuArchiveKey --keyid 437D05B5 --keyserver keyserver.ubuntu.com
--------------------------------------------------------------------------------
# same thing with other keyserver
__apt_key UbuntuArchiveKey --keyid 437D05B5 --keyserver keyserver.ubuntu.com
SEE ALSO
--------
- cdist-type(7)
- `cdist-type(7) <cdist-type.html>`_
COPYING
......
cdist-type__apt_key_uri(7)
==========================
Steven Armstrong <steven-cdist--@--armstrong.cc>
Add apt key from uri
NAME
----
cdist-type__apt_key_uri - add apt key from uri
Steven Armstrong <steven-cdist--@--armstrong.cc>
DESCRIPTION
......@@ -15,16 +12,16 @@ Download a key from an uri and add it to the apt keyring.
REQUIRED PARAMETERS
-------------------
uri::
uri
the uri from which to download the key
OPTIONAL PARAMETERS
-------------------
state::
state
'present' or 'absent', defaults to 'present'
name::
name
a name for this key, used when testing if it is already installed.
Defaults to __object_id
......@@ -32,17 +29,17 @@ name::
EXAMPLES
--------
--------------------------------------------------------------------------------
__apt_key_uri rabbitmq \
--name 'RabbitMQ Release Signing Key <info@rabbitmq.com>' \
--uri http://www.rabbitmq.com/rabbitmq-signing-key-public.asc \
--state present
--------------------------------------------------------------------------------
.. code-block:: sh
__apt_key_uri rabbitmq \
--name 'RabbitMQ Release Signing Key <info@rabbitmq.com>' \
--uri http://www.rabbitmq.com/rabbitmq-signing-key-public.asc \
--state present
SEE ALSO
--------
- cdist-type(7)
- `cdist-type(7) <cdist-type.html>`_
COPYING
......
cdist-type__apt_norecommends(7)
===============================
Steven Armstrong <steven-cdist--@--armstrong.cc>
Configure apt to not install recommended packages
NAME
----
cdist-type__apt_norecommends - configure apt to not install recommended packages
Steven Armstrong <steven-cdist--@--armstrong.cc>
DESCRIPTION
......@@ -26,14 +23,14 @@ None.
EXAMPLES
--------
--------------------------------------------------------------------------------
__apt_norecommends
--------------------------------------------------------------------------------
.. code-block:: sh
__apt_norecommends
SEE ALSO
--------
- cdist-type(7)
- `cdist-type(7) <cdist-type.html>`_
COPYING
......
cdist-type__apt_ppa(7)
======================
Steven Armstrong <steven-cdist--@--armstrong.cc>
Manage ppa repositories
NAME
----
cdist-type__apt_ppa - Manage ppa repositories
Steven Armstrong <steven-cdist--@--armstrong.cc>
DESCRIPTION
......@@ -15,7 +12,7 @@ This cdist type allows manage ubuntu ppa repositories.
REQUIRED PARAMETERS
-------------------
state::
state
The state the ppa should be in, either 'present' or 'absent'.
Defaults to 'present'
......@@ -28,20 +25,20 @@ None.
EXAMPLES
--------
--------------------------------------------------------------------------------
# Enable a ppa repository
__apt_ppa ppa:sans-intern/missing-bits
# same as
__apt_ppa ppa:sans-intern/missing-bits --state present
.. code-block:: sh
# Enable a ppa repository
__apt_ppa ppa:sans-intern/missing-bits
# same as
__apt_ppa ppa:sans-intern/missing-bits --state present
# Disable a ppa repository
__apt_ppa ppa:sans-intern/missing-bits --state absent
--------------------------------------------------------------------------------
# Disable a ppa repository
__apt_ppa ppa:sans-intern/missing-bits --state absent
SEE ALSO
--------
- cdist-type(7)
- `cdist-type(7) <cdist-type.html>`_
COPYING
......
cdist-type__apt_source(7)
=========================
Steven Armstrong <steven-cdist--@--armstrong.cc>
Manage apt sources
NAME
----
cdist-type__apt_source - manage apt sources
Steven Armstrong <steven-cdist--@--armstrong.cc>
DESCRIPTION
......@@ -15,52 +12,52 @@ This cdist type allows you to manage apt sources.
REQUIRED PARAMETERS
-------------------
uri::
uri
the uri to the apt repository
OPTIONAL PARAMETERS
-------------------
arch::
arch
set this if you need to force and specific arch (ubuntu specific)
state::
state
'present' or 'absent', defaults to 'present'
distribution::
distribution
the distribution codename to use. Defaults to DISTRIB_CODENAME from
the targets /etc/lsb-release
component::
component
space delimited list of components to enable. Defaults to an empty string.
BOOLEAN PARAMETERS
------------------
include-src::
include-src
include deb-src entries
EXAMPLES
--------
--------------------------------------------------------------------------------
__apt_source rabbitmq \
--uri http://www.rabbitmq.com/debian/ \
--distribution testing \
--component main \
--include-src \
--state present
.. code-block:: sh
__apt_source rabbitmq \
--uri http://www.rabbitmq.com/debian/ \
--distribution testing \
--component main \
--include-src \
--state present
__apt_source canonical_partner \
--uri http://archive.canonical.com/ \
--component partner --state present
--------------------------------------------------------------------------------
__apt_source canonical_partner \
--uri http://archive.canonical.com/ \
--component partner --state present
SEE ALSO
--------
- cdist-type(7)
- `cdist-type(7) <cdist-type.html>`_
COPYING
......
cdist-type__apt_update_index(7)
===============================
Steven Armstrong <steven-cdist--@--armstrong.cc>
Update apt's package index
NAME
----
cdist-type__apt_update_index - Update apt's package index
Steven Armstrong <steven-cdist--@--armstrong.cc>
DESCRIPTION
......@@ -25,14 +22,14 @@ None.
EXAMPLES
--------
--------------------------------------------------------------------------------
__apt_update_index
--------------------------------------------------------------------------------
.. code-block:: sh
__apt_update_index
SEE ALSO
--------
- cdist-type(7)
- `cdist-type(7) <cdist-type.html>`_
COPYING
......
cdist-type__block(7)
====================
Steven Armstrong <steven-cdist--@--armstrong.cc>
Manage blocks of text in files
NAME
----
cdist-type__block - Manage blocks of text in files
Steven Armstrong <steven-cdist--@--armstrong.cc>
DESCRIPTION
......@@ -18,62 +15,62 @@ of text.
REQUIRED PARAMETERS
-------------------
text::
text
the text to manage.
If text is '-' (dash), take what was written to stdin as the text.
OPTIONAL PARAMETERS
-------------------
file::
file
the file in which to manage the text block.
Defaults to object_id.
prefix::
prefix
the prefix to add before the text.
Defaults to #cdist:__block/$__object_id
suffix::
suffix
the suffix to add after the text.
Defaults to #/cdist:__block/$__object_id
state::
state
'present' or 'absent', defaults to 'present'
MESSAGES
--------
add::
add
block was added
update::
update
block was updated/changed
remove::
remove
block was removed
EXAMPLES
--------
--------------------------------------------------------------------------------
# text from argument
__block /path/to/file \
--prefix '#start' \
--suffix '#end' \
--text 'some\nblock of\ntext'
.. code-block:: sh
# text from argument
__block /path/to/file \
--prefix '#start' \
--suffix '#end' \
--text 'some\nblock of\ntext'
# text from stdin
__block some-id \
--file /path/to/file \
--text - << DONE
here some block
of text
DONE
--------------------------------------------------------------------------------
# text from stdin
__block some-id \
--file /path/to/file \
--text - << DONE
here some block
of text
DONE
SEE ALSO
--------
- cdist-type(7)
- `cdist-type(7) <cdist-type.html>`_
COPYING
......
cdist-type__ccollect_source(7)
==============================
Nico Schottelius <nico-cdist--@--schottelius.org>
Manage ccollect sources
NAME
----
cdist-type__ccollect_source - Manage ccollect sources
Nico Schottelius <nico-cdist--@--schottelius.org>
DESCRIPTION
-----------
This cdist type allows you to create or delete ccollect sources.
REQUIRED PARAMETERS
-------------------
source::
source
The source from which to backup
destination::
destination
The destination directory
OPTIONAL PARAMETERS
-------------------
state::
state
'present' or 'absent', defaults to 'present'
ccollectconf::
ccollectconf
The CCOLLECT_CONF directory. Defaults to /etc/ccollect.
OPTIONAL MULTIPLE PARAMETERS
----------------------------
exclude::
exclude
Paths to exclude of backup
BOOLEAN PARAMETERS
------------------
verbose::
verbose
Whether to report backup verbosely
EXAMPLES
--------
--------------------------------------------------------------------------------
__ccollect_source doc.ungleich.ch \
--source doc.ungleich.ch:/ \
--destination /backup/doc.ungleich.ch \
--exclude '/proc/*' --exclude '/sys/*' \
--verbose
.. code-block:: sh
--------------------------------------------------------------------------------
__ccollect_source doc.ungleich.ch \
--source doc.ungleich.ch:/ \
--destination /backup/doc.ungleich.ch \
--exclude '/proc/*' --exclude '/sys/*' \
--verbose
SEE ALSO
--------
- cdist-type(7)
- `cdist-type(7) <cdist-type.html>`_
- ccollect(1)
- http://www.nico.schottelius.org/software/ccollect/
......
cdist-type__cdist(7)
====================
Nico Schottelius <nico-cdist--@--schottelius.org>
Manage cdist installations
NAME
----
cdist-type__cdist - Manage cdist installations
Nico Schottelius <nico-cdist--@--schottelius.org>
DESCRIPTION
......@@ -26,16 +23,16 @@ REQUIRED PARAMETERS
OPTIONAL PARAMETERS
-------------------
username::
username
Select the user to create for the cdist installation.
Defaults to "cdist".
source::
source
Select the source from which to clone cdist from.
Defaults to "git://github.com/telmich/cdist.git".
branch::
branch