Auto-generate configspec.rst

Automatically generate configspec.rst when building the documentation
(this includes in RTD).

.gitignore

@@ -11,3 +11,4 @@ dist/
 .coverage
 .cache
 htmlcov
+doc/source/configspec.rst

doc/Makefile

@@ -49,38 +49,38 @@ help:
 clean:
 	rm -rf $(BUILDDIR)/*
 
-html:source
+html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-dirhtml:source
+dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-singlehtml:source
+singlehtml:
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
-pickle:source
+pickle:
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
-json:source
+json:
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp:source
+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."
 
-qthelp:source
+qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -89,7 +89,7 @@ qthelp:source
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/khal.qhc"
 
-devhelp:source
+devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -98,83 +98,80 @@ devhelp:source
 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/khal"
 	@echo "# devhelp"
 
-epub:source
+epub:
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
-latex:source
+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)."
 
-latexpdf:source
+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."
 
-latexpdfja:source
+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."
 
-text:source
+text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
-man:source
+man:
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
-texinfo:source
+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)."
 
-info:source
+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."
 
-gettext:source
+gettext:
 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
-changes:source
+changes:
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
-linkcheck:source
+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."
 
-doctest:source
+doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
-xml:source
+xml:
 	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
 	@echo
 	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
 
-pseudoxml:source
+pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
-
-source:
-	make -C source

doc/source/conf.py

@@ -12,13 +12,85 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import validate
+from configobj import ConfigObj
+
 import khal
 
 # 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('.'))
 
+# -- Generate configspec.rst ----------------------------------------------
+
+specpath = '../../khal/settings/khal.spec'
+config = ConfigObj(
+    None, configspec=specpath, stringify=False, list_values=False
+)
+validator = validate.Validator()
+config.validate(validator)
+spec = config.configspec
+
+
+def write_section(specsection, secname, key, comment, output):
+    # why is _parse_check a "private" method? seems to be rather useful...
+    # we don't need fun_kwargs
+    fun_name, fun_args, fun_kwargs, default = validator._parse_check(specsection)
+    output.write('\n.. _{}-{}:'.format(secname, key))
+    output.write('\n')
+    output.write('\n.. object:: {}\n'.format(key))
+    output.write('\n')
+    output.write('    ' + '\n    '.join([line.strip('# ') for line in comment]))
+    output.write('\n')
+    if fun_name == 'option':
+        fun_args = ['*{}*'.format(arg) for arg in fun_args]
+        fun_args = fun_args[:-2] + [fun_args[-2] + ' and ' + fun_args[-1]]
+        fun_name += ', allowed values are {}'.format(', '.join(fun_args))
+        fun_args = []
+    if fun_name == 'integer' and len(fun_args) == 2:
+        fun_name += ', allowed values are between {} and {}'.format(
+            fun_args[0], fun_args[1])
+        fun_args = []
+    output.write('\n')
+    if fun_name in ['expand_db_path', 'expand_path']:
+        fun_name = 'string'
+    elif fun_name in ['force_list']:
+        fun_name = 'list'
+        if isinstance(default, list):
+            default = ['space' if one == ' ' else one for one in default]
+            default = ', '.join(default)
+
+    output.write('      :type: {}'.format(fun_name))
+    output.write('\n')
+    if fun_args != []:
+        output.write('      :args: {}'.format(fun_args))
+        output.write('\n')
+    output.write('      :default: {}'.format(default))
+    output.write('\n')
+
+
+with open('configspec.rst', 'w') as f:
+    for secname in sorted(spec):
+        f.write('\n')
+        heading = 'The [{}] section'.format(secname)
+        f.write('{}\n{}'.format(heading, len(heading) * '~'))
+        f.write('\n')
+        comment = spec.comments[secname]
+        f.write('\n'.join([line[2:] for line in comment]))
+        f.write('\n')
+
+        for key, comment in sorted(spec[secname].comments.items()):
+            if key == '__many__':
+                comment = spec[secname].comments[key]
+                f.write('\n'.join([line[2:] for line in comment]))
+                f.write('\n')
+                for key, comment in sorted(spec[secname]['__many__'].comments.items()):
+                    write_section(spec[secname]['__many__'][key], secname,
+                                  key, comment, f)
+            else:
+                write_section(spec[secname][key], secname, key, comment, f)
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.

doc/source/configspec.rst

@@ -1,10 +1,3 @@
-..
-    PLEASE DO NOT EDIT THIS FILE
-    ############################
-
-    This file gets generated from `khal/khal/settings/khal.spec`. Please edit
-    that file instead and then run `make` in `khal/doc/'.
-
 
 The [calendars] section
 ~~~~~~~~~~~~~~~~~~~~~~~