forked from ungleich-public/cdist-contrib
Import html/man doc generation logic from upstream cdist
This commit is contained in:
parent
2e02c413b6
commit
9f4a85901e
10 changed files with 552 additions and 12 deletions
|
|
@ -1,14 +1,20 @@
|
||||||
stages:
|
stages:
|
||||||
- test
|
- test
|
||||||
|
- doc
|
||||||
|
|
||||||
image: code.ungleich.ch:5050/ungleich-public/cdist/cdist-ci:latest
|
image: code.ungleich.ch:5050/ungleich-public/cdist/cdist-ci:latest
|
||||||
|
|
||||||
shellcheck:
|
shellcheck:
|
||||||
stage: test
|
stage: test
|
||||||
script:
|
script:
|
||||||
- ./scripts/run-shellcheck.sh
|
- make lint
|
||||||
|
|
||||||
manpages:
|
manpages:
|
||||||
stage: test
|
stage: test
|
||||||
script:
|
script:
|
||||||
- ./scripts/run-manpage-checks.sh
|
- make check-manpages
|
||||||
|
|
||||||
|
docs:
|
||||||
|
stage: doc
|
||||||
|
script:
|
||||||
|
- make docs
|
||||||
|
|
|
||||||
70
Makefile
Normal file
70
Makefile
Normal file
|
|
@ -0,0 +1,70 @@
|
||||||
|
.PHONY: help
|
||||||
|
help:
|
||||||
|
@echo "Please use \`make <target>' where <target> is one of"
|
||||||
|
@echo "man build only man user documentation"
|
||||||
|
@echo "html build only html user documentation"
|
||||||
|
@echo "docs build both man and html user documentation"
|
||||||
|
@echo "check-manpages check for manpage in types"
|
||||||
|
@echo "lint run shellcheck on types"
|
||||||
|
@echo "check run both type manpage checks and linting"
|
||||||
|
@echo "clean clean"
|
||||||
|
|
||||||
|
DOCS_SRC_DIR=./docs/src
|
||||||
|
TYPEDIR=./type
|
||||||
|
|
||||||
|
SPHINXM=make -C $(DOCS_SRC_DIR) man
|
||||||
|
SPHINXH=make -C $(DOCS_SRC_DIR) html
|
||||||
|
SPHINXC=make -C $(DOCS_SRC_DIR) clean
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# Manpages
|
||||||
|
#
|
||||||
|
MAN7DSTDIR=$(DOCS_SRC_DIR)/man7
|
||||||
|
|
||||||
|
# Use shell / ls to get complete list - $(TYPEDIR)/*/man.rst does not work
|
||||||
|
# Using ls does not work if no file with given pattern exist, so use wildcard
|
||||||
|
MANTYPESRC=$(wildcard $(TYPEDIR)/*/man.rst)
|
||||||
|
MANTYPEPREFIX=$(subst $(TYPEDIR)/,$(MAN7DSTDIR)/cdist-type,$(MANTYPESRC))
|
||||||
|
MANTYPES=$(subst /man.rst,.rst,$(MANTYPEPREFIX))
|
||||||
|
|
||||||
|
# Link manpage: do not create man.html but correct named file
|
||||||
|
$(MAN7DSTDIR)/cdist-type%.rst: $(TYPEDIR)/%/man.rst
|
||||||
|
mkdir -p $(MAN7DSTDIR)
|
||||||
|
ln -sf "../../../$^" $@
|
||||||
|
|
||||||
|
DOCSINDEX=$(MAN7DSTDIR)/index.rst
|
||||||
|
DOCSINDEXH=$(DOCS_SRC_DIR)/index.rst.sh
|
||||||
|
|
||||||
|
$(DOCSINDEX): $(DOCSINDEXH)
|
||||||
|
$(DOCSINDEXH)
|
||||||
|
|
||||||
|
# Manpages: .cdist Types
|
||||||
|
DOT_CDIST_PATH=${HOME}/.cdist
|
||||||
|
DOTMAN7DSTDIR=$(MAN7DSTDIR)
|
||||||
|
DOTTYPEDIR=$(DOT_CDIST_PATH)/type
|
||||||
|
|
||||||
|
# Link manpage: do not create man.html but correct named file
|
||||||
|
$(DOTMAN7DSTDIR)/cdist-type%.rst: $(DOTTYPEDIR)/%/man.rst
|
||||||
|
ln -sf "$^" $@
|
||||||
|
|
||||||
|
man: $(MANTYPES) $(DOCSINDEX)
|
||||||
|
$(SPHINXM)
|
||||||
|
|
||||||
|
html: $(MANTYPES) $(DOCSINDEX)
|
||||||
|
$(SPHINXH)
|
||||||
|
|
||||||
|
docs: man html
|
||||||
|
|
||||||
|
check-manpages:
|
||||||
|
./scripts/run-manpage-checks.sh
|
||||||
|
|
||||||
|
lint:
|
||||||
|
./scripts/run-shellcheck.sh
|
||||||
|
|
||||||
|
check: check-manpages lint
|
||||||
|
|
||||||
|
clean:
|
||||||
|
$(SPHINXC)
|
||||||
|
rm -f docs/src/index.rst
|
||||||
|
rm -rf docs/src/man7/
|
||||||
|
rm -rf docs/src/__pycache__/
|
||||||
235
docs/src/Makefile
Normal file
235
docs/src/Makefile
Normal file
|
|
@ -0,0 +1,235 @@
|
||||||
|
# Makefile for Sphinx documentation
|
||||||
|
#
|
||||||
|
|
||||||
|
# You can set these variables from the command line.
|
||||||
|
SPHINXOPTS ?=
|
||||||
|
SPHINXBUILD ?= sphinx-build
|
||||||
|
PAPER ?=
|
||||||
|
BUILDDIR ?= ../dist
|
||||||
|
# for cache, etc.
|
||||||
|
_BUILDDIR = _build
|
||||||
|
|
||||||
|
# User-friendly check for sphinx-build
|
||||||
|
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
|
||||||
|
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/)
|
||||||
|
endif
|
||||||
|
|
||||||
|
# Internal variables.
|
||||||
|
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||||
|
PAPEROPT_letter = -D latex_paper_size=letter
|
||||||
|
ALLSPHINXOPTS = -d $(_BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||||
|
# the i18n builder cannot share the environment and doctrees with the others
|
||||||
|
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||||
|
|
||||||
|
.PHONY: help
|
||||||
|
help:
|
||||||
|
@echo "Please use \`make <target>' where <target> is one of"
|
||||||
|
@echo " html to make standalone HTML files"
|
||||||
|
@echo " dirhtml to make HTML files named index.html in directories"
|
||||||
|
@echo " singlehtml to make a single large HTML file"
|
||||||
|
@echo " pickle to make pickle files"
|
||||||
|
@echo " json to make JSON files"
|
||||||
|
@echo " htmlhelp to make HTML files and a HTML help project"
|
||||||
|
@echo " qthelp to make HTML files and a qthelp project"
|
||||||
|
@echo " applehelp to make an Apple Help Book"
|
||||||
|
@echo " devhelp to make HTML files and a Devhelp project"
|
||||||
|
@echo " epub to make an epub"
|
||||||
|
@echo " epub3 to make an epub3"
|
||||||
|
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||||
|
@echo " latexpdf to make LaTeX files and run them through pdflatex"
|
||||||
|
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
|
||||||
|
@echo " text to make text files"
|
||||||
|
@echo " man to make manual pages"
|
||||||
|
@echo " texinfo to make Texinfo files"
|
||||||
|
@echo " info to make Texinfo files and run them through makeinfo"
|
||||||
|
@echo " gettext to make PO message catalogs"
|
||||||
|
@echo " changes to make an overview of all changed/added/deprecated items"
|
||||||
|
@echo " xml to make Docutils-native XML files"
|
||||||
|
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
|
||||||
|
@echo " linkcheck to check all external links for integrity"
|
||||||
|
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
||||||
|
@echo " coverage to run coverage check of the documentation (if enabled)"
|
||||||
|
@echo " dummy to check syntax errors of document sources"
|
||||||
|
|
||||||
|
.PHONY: clean
|
||||||
|
clean:
|
||||||
|
rm -rf $(BUILDDIR)/*
|
||||||
|
rm -rf $(_BUILDDIR)/*
|
||||||
|
|
||||||
|
.PHONY: html
|
||||||
|
html:
|
||||||
|
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||||
|
|
||||||
|
.PHONY: dirhtml
|
||||||
|
dirhtml:
|
||||||
|
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
|
||||||
|
|
||||||
|
.PHONY: singlehtml
|
||||||
|
singlehtml:
|
||||||
|
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
|
||||||
|
|
||||||
|
.PHONY: pickle
|
||||||
|
pickle:
|
||||||
|
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
|
||||||
|
@echo
|
||||||
|
@echo "Build finished; now you can process the pickle files."
|
||||||
|
|
||||||
|
.PHONY: json
|
||||||
|
json:
|
||||||
|
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
|
||||||
|
@echo
|
||||||
|
@echo "Build finished; now you can process the JSON files."
|
||||||
|
|
||||||
|
.PHONY: htmlhelp
|
||||||
|
htmlhelp:
|
||||||
|
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
|
||||||
|
@echo
|
||||||
|
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||||
|
".hhp project file in $(BUILDDIR)/htmlhelp."
|
||||||
|
|
||||||
|
.PHONY: qthelp
|
||||||
|
qthelp:
|
||||||
|
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
|
||||||
|
@echo
|
||||||
|
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||||
|
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
||||||
|
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/cdist-docs.qhcp"
|
||||||
|
@echo "To view the help file:"
|
||||||
|
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/cdist-docs.qhc"
|
||||||
|
|
||||||
|
.PHONY: applehelp
|
||||||
|
applehelp:
|
||||||
|
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
|
||||||
|
@echo "N.B. You won't be able to view it unless you put it in" \
|
||||||
|
"~/Library/Documentation/Help or install it in your application" \
|
||||||
|
"bundle."
|
||||||
|
|
||||||
|
.PHONY: devhelp
|
||||||
|
devhelp:
|
||||||
|
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
|
||||||
|
@echo
|
||||||
|
@echo "Build finished."
|
||||||
|
@echo "To view the help file:"
|
||||||
|
@echo "# mkdir -p $$HOME/.local/share/devhelp/cdist-docs"
|
||||||
|
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/cdist-docs"
|
||||||
|
@echo "# devhelp"
|
||||||
|
|
||||||
|
.PHONY: epub
|
||||||
|
epub:
|
||||||
|
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
|
||||||
|
|
||||||
|
.PHONY: epub3
|
||||||
|
epub3:
|
||||||
|
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
|
||||||
|
|
||||||
|
.PHONY: latex
|
||||||
|
latex:
|
||||||
|
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||||
|
@echo
|
||||||
|
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
|
||||||
|
@echo "Run \`make' in that directory to run these through (pdf)latex" \
|
||||||
|
"(use \`make latexpdf' here to do that automatically)."
|
||||||
|
|
||||||
|
.PHONY: latexpdf
|
||||||
|
latexpdf:
|
||||||
|
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||||
|
@echo "Running LaTeX files through pdflatex..."
|
||||||
|
$(MAKE) -C $(BUILDDIR)/latex all-pdf
|
||||||
|
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||||
|
|
||||||
|
.PHONY: latexpdfja
|
||||||
|
latexpdfja:
|
||||||
|
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||||
|
@echo "Running LaTeX files through platex and dvipdfmx..."
|
||||||
|
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
|
||||||
|
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||||
|
|
||||||
|
.PHONY: text
|
||||||
|
text:
|
||||||
|
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The text files are in $(BUILDDIR)/text."
|
||||||
|
|
||||||
|
.PHONY: man
|
||||||
|
man:
|
||||||
|
$(SPHINXBUILD) -b cman $(ALLSPHINXOPTS) $(BUILDDIR)/man
|
||||||
|
mkdir -p $(BUILDDIR)/man/man7
|
||||||
|
mv -f $(BUILDDIR)/man/*.7 $(BUILDDIR)/man/man7/
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
|
||||||
|
|
||||||
|
.PHONY: texinfo
|
||||||
|
texinfo:
|
||||||
|
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
|
||||||
|
@echo "Run \`make' in that directory to run these through makeinfo" \
|
||||||
|
"(use \`make info' here to do that automatically)."
|
||||||
|
|
||||||
|
.PHONY: info
|
||||||
|
info:
|
||||||
|
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||||
|
@echo "Running Texinfo files through makeinfo..."
|
||||||
|
make -C $(BUILDDIR)/texinfo info
|
||||||
|
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
|
||||||
|
|
||||||
|
.PHONY: gettext
|
||||||
|
gettext:
|
||||||
|
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
|
||||||
|
|
||||||
|
.PHONY: changes
|
||||||
|
changes:
|
||||||
|
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
|
||||||
|
@echo
|
||||||
|
@echo "The overview file is in $(BUILDDIR)/changes."
|
||||||
|
|
||||||
|
.PHONY: linkcheck
|
||||||
|
linkcheck:
|
||||||
|
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
|
||||||
|
@echo
|
||||||
|
@echo "Link check complete; look for any errors in the above output " \
|
||||||
|
"or in $(BUILDDIR)/linkcheck/output.txt."
|
||||||
|
|
||||||
|
.PHONY: doctest
|
||||||
|
doctest:
|
||||||
|
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
|
||||||
|
@echo "Testing of doctests in the sources finished, look at the " \
|
||||||
|
"results in $(BUILDDIR)/doctest/output.txt."
|
||||||
|
|
||||||
|
.PHONY: coverage
|
||||||
|
coverage:
|
||||||
|
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
|
||||||
|
@echo "Testing of coverage in the sources finished, look at the " \
|
||||||
|
"results in $(BUILDDIR)/coverage/python.txt."
|
||||||
|
|
||||||
|
.PHONY: xml
|
||||||
|
xml:
|
||||||
|
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
|
||||||
|
|
||||||
|
.PHONY: pseudoxml
|
||||||
|
pseudoxml:
|
||||||
|
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
|
||||||
|
|
||||||
|
.PHONY: dummy
|
||||||
|
dummy:
|
||||||
|
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
|
||||||
|
@echo
|
||||||
|
@echo "Build finished. Dummy builder generates no files."
|
||||||
101
docs/src/conf.py
Normal file
101
docs/src/conf.py
Normal file
|
|
@ -0,0 +1,101 @@
|
||||||
|
#!/usr/bin/env python3
|
||||||
|
|
||||||
|
import sys
|
||||||
|
import os
|
||||||
|
import sphinx_rtd_theme
|
||||||
|
|
||||||
|
from datetime import date
|
||||||
|
|
||||||
|
# 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.
|
||||||
|
# sys.path.insert(0, os.path.abspath('.'))
|
||||||
|
sys.path.insert(0, os.path.abspath(os.path.join(
|
||||||
|
os.path.dirname(os.path.realpath(__file__)), "..", "..")))
|
||||||
|
|
||||||
|
# -- General configuration ------------------------------------------------
|
||||||
|
|
||||||
|
# If your documentation needs a minimal Sphinx version, state it here.
|
||||||
|
# needs_sphinx = '1.0'
|
||||||
|
|
||||||
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||||
|
# ones.
|
||||||
|
extensions = [
|
||||||
|
'docs.src.manpage',
|
||||||
|
'sphinx.ext.extlinks',
|
||||||
|
]
|
||||||
|
|
||||||
|
# The suffix(es) of source filenames.
|
||||||
|
# You can specify multiple suffix as a list of string:
|
||||||
|
source_suffix = ['.rst']
|
||||||
|
|
||||||
|
# The encoding of source files.
|
||||||
|
# source_encoding = 'utf-8-sig'
|
||||||
|
|
||||||
|
# The master toctree document.
|
||||||
|
master_doc = 'index'
|
||||||
|
|
||||||
|
# General information about the project.
|
||||||
|
project = 'cdist-contrib'
|
||||||
|
copyright = 'cdist-contrib contributors'
|
||||||
|
|
||||||
|
# The version info for the project you're documenting, acts as replacement for
|
||||||
|
# |version| and |release|, also used in various other places throughout the
|
||||||
|
# built documents.
|
||||||
|
|
||||||
|
version = str(date.today())
|
||||||
|
release = os.popen('git rev-parse HEAD').read()
|
||||||
|
|
||||||
|
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||||
|
# for a list of supported languages.
|
||||||
|
#
|
||||||
|
# This is also used if you do content translation via gettext catalogs.
|
||||||
|
# Usually you set "language" from the command line for these cases.
|
||||||
|
language = None
|
||||||
|
|
||||||
|
# The name of the Pygments (syntax highlighting) style to use.
|
||||||
|
pygments_style = 'sphinx'
|
||||||
|
|
||||||
|
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||||
|
todo_include_todos = False
|
||||||
|
|
||||||
|
# -- 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 = 'sphinx_rtd_theme'
|
||||||
|
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||||
|
|
||||||
|
# Output file base name for HTML help builder.
|
||||||
|
htmlhelp_basename = 'cdistcontribdoc'
|
||||||
|
|
||||||
|
# -- Options for manual page output ---------------------------------------
|
||||||
|
|
||||||
|
# One entry per manual page. List of tuples
|
||||||
|
# (source start file, name, description, authors, manual section).
|
||||||
|
root_mandir = os.path.dirname(os.path.realpath(__file__))
|
||||||
|
mandirs = []
|
||||||
|
for mansubdir in ('man7',):
|
||||||
|
mandirs.append((os.path.join(root_mandir, mansubdir), mansubdir[-1]))
|
||||||
|
man_pages = []
|
||||||
|
for mandir, section in mandirs:
|
||||||
|
for root, dirs, files in os.walk(mandir):
|
||||||
|
for fname in files:
|
||||||
|
froot, fext = os.path.splitext(fname)
|
||||||
|
if fext == '.rst':
|
||||||
|
man_page = (os.path.join('man' + str(section), froot),
|
||||||
|
froot, '', [], section)
|
||||||
|
man_pages.append(man_page)
|
||||||
|
|
||||||
|
# man_pages = [
|
||||||
|
# ('cdist-type', 'cdist-type', 'cdist-type documentation',
|
||||||
|
# [author], 1),
|
||||||
|
# ('man7/cdist-type__file', 'cdist-type__file',
|
||||||
|
# '', [], 1),
|
||||||
|
# ('cdist-type__directory', 'cdist-type__directory',
|
||||||
|
# 'cdist-type__directory documentation', [author], 1),
|
||||||
|
# ]
|
||||||
|
|
||||||
|
# If true, show URL addresses after external links.
|
||||||
|
# man_show_urls = False
|
||||||
45
docs/src/index.rst.sh
Executable file
45
docs/src/index.rst.sh
Executable file
|
|
@ -0,0 +1,45 @@
|
||||||
|
#!/bin/sh
|
||||||
|
|
||||||
|
__cdist_pwd="$(pwd -P)"
|
||||||
|
__cdist_mydir="${0%/*}";
|
||||||
|
__cdist_abs_mydir="$(cd "$__cdist_mydir" && pwd -P)"
|
||||||
|
__cdist_myname=${0##*/};
|
||||||
|
__cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname"
|
||||||
|
|
||||||
|
filename="${__cdist_myname%.sh}"
|
||||||
|
dest="$__cdist_abs_mydir/$filename"
|
||||||
|
|
||||||
|
cd "$__cdist_abs_mydir"
|
||||||
|
|
||||||
|
exec > "$dest"
|
||||||
|
cat << EOF
|
||||||
|
cdist-contrib - Community maintained cdist types
|
||||||
|
================================================
|
||||||
|
|
||||||
|
This project extends the \`cdist <https://cdi.st/>\`_ configuration management
|
||||||
|
tool with community-maitained types which are either too specific to fit/be
|
||||||
|
maintained in cdist itself or were not accepted in code cdist but could still
|
||||||
|
be useful.
|
||||||
|
|
||||||
|
Please note this project is a **rolling release**! The documentation you're
|
||||||
|
reading has been generated from the |version| state (commit |release|).
|
||||||
|
Sources are available on \`code.ungleich.ch
|
||||||
|
<https://code.ungleich.ch/ungleich-public/cdist-contrib>\`_.
|
||||||
|
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:hidden:
|
||||||
|
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# If there is no such file then ls prints error to stderr,
|
||||||
|
# so redirect stderr to /dev/null.
|
||||||
|
for type in $(ls man7/cdist-type__*.rst 2>/dev/null | LC_ALL=C sort); do
|
||||||
|
no_dir="${type#man7/}";
|
||||||
|
no_type="${no_dir#cdist-type}";
|
||||||
|
name="${no_type%.rst}";
|
||||||
|
manref="${no_dir%.rst}"
|
||||||
|
man="${manref}(7)"
|
||||||
|
|
||||||
|
echo " $name" "<man7/${manref}>"
|
||||||
|
done
|
||||||
87
docs/src/manpage.py
Normal file
87
docs/src/manpage.py
Normal file
|
|
@ -0,0 +1,87 @@
|
||||||
|
import sphinx.builders.manpage
|
||||||
|
import sphinx.writers.manpage
|
||||||
|
from docutils.frontend import OptionParser
|
||||||
|
from sphinx.util.console import bold, darkgreen
|
||||||
|
from six import string_types
|
||||||
|
from docutils.io import FileOutput
|
||||||
|
from os import path
|
||||||
|
from sphinx.util.nodes import inline_all_toctrees
|
||||||
|
from sphinx import addnodes
|
||||||
|
from sphinx.util import logging
|
||||||
|
|
||||||
|
"""
|
||||||
|
Extension based on sphinx builtin manpage.
|
||||||
|
It does not write its own .SH NAME based on config,
|
||||||
|
but leaves everything to actual reStructuredText file content.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
logger = logging.getLogger(__name__)
|
||||||
|
|
||||||
|
|
||||||
|
class ManualPageTranslator(sphinx.writers.manpage.ManualPageTranslator):
|
||||||
|
|
||||||
|
def header(self):
|
||||||
|
tmpl = (".TH \"%(title_upper)s\" \"%(manual_section)s\""
|
||||||
|
" \"%(date)s\" \"%(version)s\" \"%(manual_group)s\"\n")
|
||||||
|
return tmpl % self._docinfo
|
||||||
|
|
||||||
|
|
||||||
|
class ManualPageWriter(sphinx.writers.manpage.ManualPageWriter):
|
||||||
|
|
||||||
|
def __init__(self, builder):
|
||||||
|
super().__init__(builder)
|
||||||
|
self.translator_class = (
|
||||||
|
self.builder.get_translator_class() or ManualPageTranslator)
|
||||||
|
|
||||||
|
|
||||||
|
class ManualPageBuilder(sphinx.builders.manpage.ManualPageBuilder):
|
||||||
|
|
||||||
|
name = 'cman'
|
||||||
|
default_translator_class = ManualPageTranslator
|
||||||
|
|
||||||
|
def write(self, *ignored):
|
||||||
|
docwriter = ManualPageWriter(self)
|
||||||
|
docsettings = OptionParser(
|
||||||
|
defaults=self.env.settings,
|
||||||
|
components=(docwriter,),
|
||||||
|
read_config_files=True).get_default_values()
|
||||||
|
|
||||||
|
logger.info(bold('writing... '), nonl=True)
|
||||||
|
|
||||||
|
for info in self.config.man_pages:
|
||||||
|
docname, name, description, authors, section = info
|
||||||
|
if isinstance(authors, string_types):
|
||||||
|
if authors:
|
||||||
|
authors = [authors]
|
||||||
|
else:
|
||||||
|
authors = []
|
||||||
|
|
||||||
|
targetname = '%s.%s' % (name, section)
|
||||||
|
logger.info(darkgreen(targetname) + ' { ', nonl=True)
|
||||||
|
destination = FileOutput(
|
||||||
|
destination_path=path.join(self.outdir, targetname),
|
||||||
|
encoding='utf-8')
|
||||||
|
|
||||||
|
tree = self.env.get_doctree(docname)
|
||||||
|
docnames = set()
|
||||||
|
largetree = inline_all_toctrees(self, docnames, docname, tree,
|
||||||
|
darkgreen, [docname])
|
||||||
|
logger.info('} ', nonl=True)
|
||||||
|
self.env.resolve_references(largetree, docname, self)
|
||||||
|
# remove pending_xref nodes
|
||||||
|
for pendingnode in largetree.traverse(addnodes.pending_xref):
|
||||||
|
pendingnode.replace_self(pendingnode.children)
|
||||||
|
|
||||||
|
largetree.settings = docsettings
|
||||||
|
largetree.settings.title = name
|
||||||
|
largetree.settings.subtitle = description
|
||||||
|
largetree.settings.authors = authors
|
||||||
|
largetree.settings.section = section
|
||||||
|
|
||||||
|
docwriter.write(largetree, destination)
|
||||||
|
logger.info("")
|
||||||
|
|
||||||
|
|
||||||
|
def setup(app):
|
||||||
|
app.add_builder(ManualPageBuilder)
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
cdist-type__matrix_element(7)
|
cdist-type__matrix_element(7)
|
||||||
======================
|
=============================
|
||||||
|
|
||||||
NAME
|
NAME
|
||||||
----
|
----
|
||||||
|
|
|
||||||
|
|
@ -33,7 +33,7 @@ EXAMPLES
|
||||||
|
|
||||||
.. code-block:: sh
|
.. code-block:: sh
|
||||||
|
|
||||||
__matterbridge --version 1.16.3 --config - << EOF
|
__matterbridge --version 1.16.3 --config - <<- EOF
|
||||||
[...]
|
[...]
|
||||||
EOF
|
EOF
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -122,7 +122,6 @@ basepath
|
||||||
webroot ``/``. For example, if installed at https://example.com/netbox/, set
|
webroot ``/``. For example, if installed at https://example.com/netbox/, set
|
||||||
the value ``netbox/``.
|
the value ``netbox/``.
|
||||||
|
|
||||||
http-proxy
|
|
||||||
https-proxy
|
https-proxy
|
||||||
Proxy which will be used with any HTTP request like webhooks.
|
Proxy which will be used with any HTTP request like webhooks.
|
||||||
|
|
||||||
|
|
@ -171,12 +170,12 @@ redis-ssl
|
||||||
|
|
||||||
smtp-use-tls
|
smtp-use-tls
|
||||||
Uses TLS to connect to the SMTP email server. `See documentation
|
Uses TLS to connect to the SMTP email server. `See documentation
|
||||||
<https://docs.djangoproject.com/en/3.1/ref/settings/#email-use-tls>`_
|
<https://docs.djangoproject.com/en/3.1/ref/settings/#email-use-tls>`__
|
||||||
for more information.
|
for more information.
|
||||||
|
|
||||||
smtp-use-ssl
|
smtp-use-ssl
|
||||||
Uses implicit TLS with the SMTP email server. `See documentation
|
Uses implicit TLS with the SMTP email server. `See documentation
|
||||||
<https://docs.djangoproject.com/en/3.1/ref/settings/#email-use-ssl>`_
|
<https://docs.djangoproject.com/en/3.1/ref/settings/#email-use-ssl>`__
|
||||||
for more information.
|
for more information.
|
||||||
|
|
||||||
login-required
|
login-required
|
||||||
|
|
|
||||||
|
|
@ -65,10 +65,7 @@ protocol
|
||||||
parameter. Possible values are ``uwsgi``, ``http``, ``fastcgi`` and
|
parameter. Possible values are ``uwsgi``, ``http``, ``fastcgi`` and
|
||||||
``scgi``. If nothing given, it defaults to ``uwsgi``.
|
``scgi``. If nothing given, it defaults to ``uwsgi``.
|
||||||
|
|
||||||
uwsgi-bind
|
scgi-bind, uwsgi-bind, http-bind, fastcgi-bind
|
||||||
http-bind
|
|
||||||
fastcgi-bind
|
|
||||||
scgi-bind
|
|
||||||
Bind the application to a specific protocol instead of implicit uwsgi via
|
Bind the application to a specific protocol instead of implicit uwsgi via
|
||||||
``--bind-to``. If such parameter given, ``--bind-to`` will be ignored. Must
|
``--bind-to``. If such parameter given, ``--bind-to`` will be ignored. Must
|
||||||
be a UNIX/TCP socket. Can be set multiple times.
|
be a UNIX/TCP socket. Can be set multiple times.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue