Commit f9e19f9c authored by Nicolas Dandrimont's avatar Nicolas Dandrimont

Wire up the ansible per-role documentation into the sphinx build

This enables recommonmark to support markdown as input files, and copies the
current role READMEs into a toctree that's generated on the fly.
parent c046119a
Pipeline #34545 passed with stage
in 2 minutes and 35 seconds
......@@ -2,6 +2,8 @@
/roles/tftp-server/files/d-i/preseed_local_*.cfg
/roles/tftp-server/files/scripts/late_command.cfg
/site.retry
/docs/ansible_roles/
/docs/ansible_roles.rst
/docs/_build
/usbinst/cache/
/usbinst/configs/
......
......@@ -40,7 +40,7 @@ pages:
image: debian:sid
script:
- apt-get update
- apt-get -y install python3-sphinx make
- apt-get -y install python3-sphinx python3-recommonmark make
- cd docs
- make html
- mv _build/html/ ../public/
......
......@@ -26,40 +26,64 @@ help:
.PHONY: clean
clean:
rm -rf $(BUILDDIR)/*
rm -rf $(BUILDDIR)/* ansible_roles ansible_roles.rst
.PHONY: html
html:
html: ansible_roles.rst
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
.PHONY: dirhtml
dirhtml:
dirhtml: ansible_roles.rst
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
.PHONY: singlehtml
singlehtml:
singlehtml: ansible_roles.rst
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
.PHONY: man
man:
man: ansible_roles.rst
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
.PHONY: changes
changes:
changes: ansible_roles.rst
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
.PHONY: dummy
dummy:
dummy: ansible_roles.rst
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
@echo
@echo "Build finished. Dummy builder generates no files."
ROLE_READMES := $(wildcard ../roles/*/README.md)
ROLE_TARGETS := $(patsubst ../roles/%/README.md,ansible_roles/%.md,$(ROLE_READMES))
ansible_roles:
mkdir -p ansible_roles
ansible_roles/%.md: ../roles/%/README.md ansible_roles
cp $< $@
ansible_roles.rst: $(ROLE_TARGETS)
( \
echo .. _ansible_roles:; \
echo; \
echo "Ansible role documentation"; \
echo "=========================="; \
echo; \
echo .. toctree::; \
echo; \
for file in $^; do \
echo " $$file"; \
done \
) > ansible_roles.rst
......@@ -6,6 +6,8 @@
# sys.path.insert(0, os.path.abspath('.'))
import datetime
from recommonmark.parser import CommonMarkParser
# -- General configuration ------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
......@@ -23,7 +25,11 @@ templates_path = ['_templates']
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
source_suffix = ['.rst', '.md']
source_parsers = {
'.md': CommonMarkParser,
}
# The encoding of source files.
source_encoding = 'utf-8-sig'
......
......@@ -11,4 +11,5 @@ Ansible Documentation
opsis.rst
advanced_usage.rst
usb.rst
ansible_roles.rst
contact.rst
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