diff options
| -rw-r--r-- | commands/README.md | 24 | ||||
| -rw-r--r-- | doc/Makefile | 72 | ||||
| -rw-r--r-- | doc/README.md | 12 | ||||
| -rw-r--r-- | doc/conf.py | 14 | ||||
| -rw-r--r-- | doc/index.rst | 1 |
5 files changed, 112 insertions, 11 deletions
diff --git a/commands/README.md b/commands/README.md index 09481de..0e926a7 100644 --- a/commands/README.md +++ b/commands/README.md @@ -19,6 +19,13 @@ It has the following structrure: │ │ └── <provider_prefix> # library as an interface to providers │ │ ├── cmd.py # definitions of commands │ │ └── __init__.py + │ ├── doc # usage and developer documentation + │ │ ├── cmdline.generated + │ │ ├── cmdline.rst # source in reStructured text [rst] + │ │ ├── conf.py # documentation configuration + │ │ ├── index.rst # top-level documentation source + │ │ ├── Makefile + │ │ └── python.rst # library reference source │ ├── README.md │ └── setup.py │ ... ... @@ -33,6 +40,18 @@ system management of remote hosts. Part of the interface is exported via commands to `lmi` meta-command. These, by a convention, are defined in `lmi.scripts.<provider_prefix>.cmd` module. +### Documentation directory +Please stick to the structure presented above. It makes it easy to include +library documents into the global documentation. + + * `cmdline.generated` is a file in [*reStructuredText*][see rst] format generated + with `tools/help2rst` script from command's usage string. + * `cmdline.rst` is a file including the one above and providing some additional + informations related to command's invocation. + * `python.rst` just lists the modules from `lmi.scripts.<provider_prefix>` to + document for python reference. + * `index.rst` binds all the other files together. + Setup file ---------- Allows to install command python egg and register their exported commands to @@ -68,7 +87,7 @@ description of *Command module* below. [a-z]+(-[a-z]+)*(\.py)? Command module ------------ +-------------- Is a python module named (by a convention) `.cmd` under your command library. It has a documentation string passeable to the `docopt` command line parser (see `http://docopt.org/`). The structure of this file is following: @@ -119,6 +138,8 @@ global variable, which holds the result of this call must be listed in available in `lmi` meta-command. ### <requirement\_string> +**This is not yet supported feature** + Allows to specify, which profiles and their specific versions are neccessary to run this command. It's format can be described by following grammar: @@ -154,3 +175,4 @@ First sequence of digits will be compared with `MajorVersion`, second to where `<class_name>` denotes the name of CIM class. And `<version>` the value of its `Version` qualifier in the mof file. +[rst]: http://sphinx-doc.org/rest.html "reStructuredText" diff --git a/doc/Makefile b/doc/Makefile index 34fcff7..8d3189f 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -2,11 +2,14 @@ # # You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build -PROJECTNAME = OpenLMIScripts +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR ?= _build +PROJECTNAME = OpenLMIScripts +COMMANDS_PATH ?= ../commands +INCLUDE_COMMANDS ?= 0 +COMMANDS ?= service software storage # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 @@ -15,7 +18,7 @@ ALLSPHINXOPTS = -n -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext mof generated +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext commands.rst all: html epub latexpdf @@ -47,8 +50,57 @@ api.rst: gendoc.sh $(wildcard ../lmi/scripts/*.py \ ../lmi/scripts/formatter/*.py) ./gendoc.sh +commands.rst: + echo "Command libraries documentation" > $@ + echo "===============================" >> $@ +ifneq ($(INCLUDE_COMMANDS), 0) + -[ -e commands ] && rm -rf commands + mkdir commands + echo "Usage and developer documentations of provider libraries" >> $@ + echo "(also called *commands*.)" >> $@ + printf "\n.. toctree::\n" >> $@ + printf " :maxdepth: 2\n\n" >> $@ + for cmd in $(COMMANDS); do \ + printf " commands/$$cmd\n" >> $@; \ + ln -s ../$(COMMANDS_PATH)/$${cmd}/doc commands/$${cmd}_docdir; \ + make -C commands/$${cmd}_docdir html; \ + title="$${cmd^} library"; \ + length=`echo "$$title" | wc -c`; \ + ( \ + printf "$${title}\n"; \ + printf -- "!%.0s" `seq 2 $$length`; \ + printf "\n\n"; \ + if [ -e commands/$${cmd}_docdir/cmdline.rst ]; then \ + sed "s,\(\.\.\s\+include::\s*\)\(.*\),\1$${cmd}_docdir/\2," \ + commands/$${cmd}_docdir/cmdline.rst \ + >commands/$${cmd}_cmdline.txt; \ + printf ".. include:: $${cmd}_cmdline.txt\n\n"; \ + fi; \ + printf "$${cmd^} library reference\n"; \ + printf -- "==========================\n"; \ + if [ -e commands/$${cmd}_docdir/python.rst ]; then \ + printf ".. toctree::\n :maxdepth: 2\n\n"; \ + printf " $${cmd}_docdir/python\n\n"; \ + else \ + printf ".. automodule:: lmi.scripts.$${cmd}\n"; \ + printf " :members:\n"; \ + fi; \ + ) > commands/$${cmd}.rst; \ + done +else + ( \ + printf "You may visit command usage and developer documentations\n"; \ + printf "on pythonhosted site:\n\n"; \ + for cmd in $(COMMANDS); do \ + printf " * \`openlmi-scripts-$${cmd}"; \ + printf " <http://pythonhosted.org/openlmi-scripts-$${cmd}>\`_\n"; \ + done \ + ) >> $@ +endif + + clean: - -rm -rf $(BUILDDIR)/* modules/ api.rst + -rm -rf $(BUILDDIR)/* modules/ api.rst commands.rst commands/ %.png: %.dia dia -e $@ $< @@ -59,7 +111,7 @@ clean: figures: -html: figures api.rst +html: figures api.rst commands.rst $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." @@ -108,12 +160,12 @@ devhelp: @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/AnacondaStorageProvider" @echo "# devhelp" -epub: figures api.rst +epub: figures api.rst commands.rst $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." -latex: figures api.rst +latex: figures api.rst commands.rst $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex sed -i 's/^\\makeindex$$/\0[columns=1]/' $(BUILDDIR)/latex/$(PROJECTNAME).tex @echo diff --git a/doc/README.md b/doc/README.md index 9a58b0c..12b6e95 100644 --- a/doc/README.md +++ b/doc/README.md @@ -5,6 +5,7 @@ It's available online on [pythonhosted][]. How to build ------------ +Supported builds are *html*, *pdflatex* and *epub*. ### Requirements @@ -14,6 +15,17 @@ How to build * `sphinx-build` - provided by package `python-sphinx` ### Steps +There are two kinds of builds available. One containing documentation of `lmi` +command libraries and one with just references to them to external sources. +Following examples will generate only *html* documentation, to make any other +just replace the `html` argument with prefered one. + +#### Including commands documentation + + INCLUDE_COMMANDS=1 make -C doc html + +#### Without commands documentation +This build is the preferred one for Python Hosted site. make -C doc html diff --git a/doc/conf.py b/doc/conf.py index bb5748a..193b861 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -18,6 +18,16 @@ import sys, os # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('../lmi')) +if os.environ.get('INCLUDE_COMMANDS', '0').lower() in {'1', 'true', 'yes'}: + commands_path = os.environ.get('COMMANDS_PATH', '../commands') + commands = os.environ.get('COMMANDS', '') + if commands: + for i, cmd in enumerate(commands.split(',')): + sys.path.insert(1 + i, os.path.join(os.path.abspath(commands_path), cmd)) + + include_commands_docs = True + include_commands = commands.split(',') + # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -274,3 +284,7 @@ texinfo_documents = [ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' + +def setup(app): + app.add_config_value('include_commands', False, 'env') + app.add_config_value('commands', '', 'env') diff --git a/doc/index.rst b/doc/index.rst index aeb1517..c95879e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -15,6 +15,7 @@ Content: configuration script-development api + commands Indices and tables ================== |