Repository : http://git.fedorahosted.org/cgit/cura-tools.git
On branch : master
commit cf2bb1c3dbaaf9552a0c78adf91d2bcf1c780f5c Author: Michal Minar miminar@redhat.com Date: Wed Sep 24 13:11:59 2014 +0200
doc: restructured
Moved all API reference under top-level heading.
Fixed some build issues. * tags were not passed correctly to sphinx
LMIShell's and metacommand's api reference is generated by single script.
Makefile.inc | 2 +- cli/lmi/scripts/common/configuration.py | 7 -- doc/src/Makefile | 30 ++++-- doc/src/conf.py.skel | 17 ++-- doc/src/genapi.sh | 181 +++++++++++++++++++++++++++++++ doc/src/scripts/Makefile | 22 +--- doc/src/scripts/devel/Makefile | 10 +-- doc/src/scripts/devel/gendoc.sh | 75 ------------- doc/src/shell/Makefile | 11 -- doc/src/shell/generate_code.py | 37 ------- 10 files changed, 217 insertions(+), 175 deletions(-)
diff --git a/Makefile.inc b/Makefile.inc index 64814cd..0b6a631 100644 --- a/Makefile.inc +++ b/Makefile.inc @@ -2,7 +2,7 @@ SELFDIR = $(dir $(lastword $(MAKEFILE_LIST))) ROOTDIR := $(SELFDIR) VERSION ?= $(shell PYTHONPATH=$(ROOTDIR)/cli python -c \ 'print(__import__("lmi.shell", fromlist=["__version__"]).__version__)') -TEMPLATES := $(wildcard *.py.skel) +TEMPLATES := $(shell find $(ROOTDIR) -name '*.py.skel') TARGETS := $(basename $(TEMPLATES))
.PHONY: setup clean-setup diff --git a/cli/lmi/scripts/common/configuration.py b/cli/lmi/scripts/common/configuration.py index f35e4c6..4e45ed7 100644 --- a/cli/lmi/scripts/common/configuration.py +++ b/cli/lmi/scripts/common/configuration.py @@ -14,13 +14,6 @@ # along with this program; if not, see http://www.gnu.org/licenses/. """ Module for Configuration class. - -Configuration ---------------------- - -.. autoclass:: Configuration - :members: - """
import os diff --git a/doc/src/Makefile b/doc/src/Makefile index 4ec89fa..ede8b55 100644 --- a/doc/src/Makefile +++ b/doc/src/Makefile @@ -3,10 +3,14 @@ include ../../Makefile.inc
BUILDDIR ?= ../build SPHINXBUILD ?= sphinx-build -ALLSPHINXOPTS ?= -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . SRCDIR ?= ../../cli PROJECTNAME := OpenLMITools WITH_COMMANDS ?= 0 +ifeq ($(WITH_COMMANDS), 1) + TAGS := $(TAGS) -t with-commands +endif +ALLSPHINXOPTS ?= -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +ALLSPHINXOPTS := $(TAGS) $(ALLSPHINXOPTS)
export WITH_COMMANDS OPENLMI_SCRIPTS_DIR
@@ -14,11 +18,9 @@ export WITH_COMMANDS OPENLMI_SCRIPTS_DIR
deps: setup make -C scripts - make -C shell
deps-%: setup BUILD=$* make -C scripts - BUILD=$* make -C shell
latexpdf-build: latex-build sed -i 's/^\makeindex$$/\0[columns=1]/' $(BUILDDIR)/latex/$(PROJECTNAME).tex @@ -44,6 +46,9 @@ index-%: subindexes-% echo ""; \ echo " shell-index"; \ echo " metacommand-index"; \ + if [ "$*" == html -o "$*" == rtd ]; then \ + echo " api"; \ + fi; \ ) > toc.txt if [ "$*" == html ]; then \ ln -sf index-$*.txt index.rst; \ @@ -54,7 +59,7 @@ index-%: subindexes-% subindexes-man: shell-index-man @echo "Built subindexes for man build."
-subindexes-%: shell-index-% metacommand-index-% +subindexes-%: shell-index-% metacommand-index-% api-% @echo "Built subindexes for $* build."
shell-index-%: @@ -89,9 +94,6 @@ shell-index-%: echo " shell/return_values"; \ echo " shell/interactive_interface"; \ echo " shell/builtins"; \ - if [ "$*" == html -o "$*" == rtd ]; then \ - echo " shell/code"; \ - fi; \ ) > shell-index.rst
metacommand-index-man: @@ -122,7 +124,17 @@ metacommand-index-%: echo " scripts/development"; \ ) > metacommand-index.rst
+api-html: deps-html api.rst + +api-rtd: deps-html api.rst + +api-%: + @echo "Skipping api reference" + +api.rst: genapi.sh $(shell find $(SRCDIR)/lmi/scripts -name '*.py' -type f) + ./genapi.sh + clean: clean-setup make -C scripts clean - make -C shell clean - -rm toc.txt *index.rst + -rm toc.txt *index.rst api.rst + -rm -rf api/ diff --git a/doc/src/conf.py.skel b/doc/src/conf.py.skel index b5923f1..2c9d300 100644 --- a/doc/src/conf.py.skel +++ b/doc/src/conf.py.skel @@ -52,9 +52,9 @@ def process_signature(app, what, name, obj, options, signature, return_annotatio
def setup(app): # Register new option to include documentation for metacommand's commands - app.add_config_value('with_commands', False, 'env') + app.add_config_value('with_commands', False, True) # Register new option to include class list and class tree in index.rst - app.add_config_value('includeClasses', 'True', True) + app.add_config_value('includeClasses', True, True) # Register a very simple lexer for syntax highlighting of a shell samples app.add_lexer("shell", ShellLexer()) # autodoc setting for __init__() doc string @@ -70,8 +70,7 @@ with_commands = False # 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. SRCDIR = os.environ.get('SRCDIR', '../../cli/lmi') -sys.path[0:0] = [os.path.abspath(os.path.join(SRCDIR, p)) for p in ( - 'scripts', 'shell')] +sys.path[0:0] = [SRCDIR]
if tags.has('with-commands'): scripts_path = os.environ.get('OPENLMI_SCRIPTS_DIR', '../openlmi-scripts') @@ -79,11 +78,11 @@ if tags.has('with-commands'): commands_dir = os.path.join(scripts_path, 'commands') if not commands: commands = [ f for f in os.listdir(commands_dir) - if os.isdir(os.path.join(commands_dir, f)) ] - if commands: - for i, cmd in enumerate(commands.split(',')): - sys.path.insert(2 + i, - os.path.join(os.path.abspath(commands_dir), cmd)) + if os.path.isdir(os.path.join(commands_dir, f)) ] + else: + commands = commands.split(',') + for i, cmd in enumerate(commands): + sys.path.insert(2 + i, os.path.join(os.path.abspath(commands_dir), cmd))
with_commands = True del scripts_path, commands, commands_dir diff --git a/doc/src/genapi.sh b/doc/src/genapi.sh new file mode 100755 index 0000000..f34ae9c --- /dev/null +++ b/doc/src/genapi.sh @@ -0,0 +1,181 @@ +#!/bin/bash +# Helper script for generating developer documentation in +# api/ and api.rst + +TOPDIR=../.. +DOCDIR=$TOPDIR/doc/src +SRCDIR=$TOPDIR/cli/lmi +WITH_COMMANDS=${WITH_COMMANDS:-0} + +function get_modules() { + pushd "$SRCDIR/$1" >/dev/null + find -type f -a -name '*.py' | \ + sed -e 's:/__init__.py$::' -e 's:^./::' | \ + grep -v "^.$" | \ + grep -v '(^|/)_' | \ + sort -u + popd >/dev/null +} + +function get_module_name() { + path=`sed -e "s:^.*${SRCDIR}/(.*)$:\1:" -e "s:/:.:g"` + basename -s .py "$path" +} + +function get_version_string() { + pushd $TOPDIR/cli >/dev/null + out=`python setup.py --version` + git_version=`git describe HEAD 2>/dev/null` + echo -n "``$out``" + if [ -n "$git_version" ]; then + echo ", git: ``$git_version``" + fi + popd >/dev/null +} + +function get_scripts_version_string() { + cat $OPENLMI_SCRIPTS_DIR/VERSION 2>/dev/null +} + +for dir in shell scripts/common; do + [ -e $DOCDIR/api/$dir ] || mkdir -p $DOCDIR/api/$dir + [ -e $DOCDIR/api/$dir ] || mkdir -p $DOCDIR/api/$dir +done + +# api.rst header +cat >$DOCDIR/api.rst <<_EOF_ +OpenLMI Tools API reference +=========================== + +This is a generated documentation from *OpenLMI Tools* sources. + +Generated from version: $(get_version_string) + +.. only:: html + + **Contents:** + +.. toctree:: + :maxdepth: 2 + + api/shell + api/scripts +_EOF_ + +cat >$DOCDIR/api/shell.rst <<_EOF_ +LMIShell API reference +====================== + +This is a generated documentation from *LMIShell*'s sources. + +Generated from version: $(get_version_string) + +.. only:: html + + **Contents:** + +.. toctree:: + :maxdepth: 2 + +_EOF_ + +cat >$DOCDIR/api/scripts.rst <<_EOF_ +LMI Scripts API reference +========================= + +This is a generated documentation from *OpenLMI Scripts* sources. This covers +everything under :py:mod:`lmi.scripts` namespace. + +:py:mod:`lmi.scripts.common` package provides useful functionality for script +development. Various scripts share this directory in order to provide +command-line interface through *LMI metacommand*. + +Generated from version: $(get_version_string) + +.. ifconfig:: with_commands + + Scripts version: $(get_scripts_version_string) + +.. only:: html + + **Contents:** + +.. toctree:: + :maxdepth: 1 + + scripts/common +_EOF_ + +cat >$DOCDIR/api/scripts/common.rst <<_EOF_ +LMI Scripts common library reference +==================================== + +This library builds on top of *LMIShell*'s functionality. It provides various +utilities and wrappers for building command-line interfaces to *OpenLMI +Providers*. + +Generated from version: $(get_version_string) + +------------------------------------------------------------------------------- + +**Exported members:** + +.. automodule:: lmi.scripts.common + :members: + +------------------------------------------------------------------------------- + +**Submodules:** + +.. toctree:: + :maxdepth: 1 + +_EOF_ + +# Generate api/shell/*.rst +for module_path in `get_modules shell`; do + if [[ "$module_path" =~ ^compat ]]; then + continue + fi + module=`echo "$module_path" | get_module_name` + len=`echo $module | wc -c` + len=$(($len-1)) + underline="" + for i in `seq $len`; do underline="=$underline"; done + echo >>$DOCDIR/api/shell.rst " shell/$module" + cat >$DOCDIR/api/shell/${module}.rst <<-_EOF_ + $module + $underline + .. automodule:: lmi.shell.$module + :members: + _EOF_ +done + +# Generate api/scripts/common/*.rst +for module_path in `get_modules scripts/common`; do + module=`echo "$module_path" | get_module_name` + len=`echo $module | wc -c` + len=$(($len-1)) + underline="" + for i in `seq $len`; do underline="=$underline"; done + echo >>$DOCDIR/api/scripts/common.rst " common/$module" + cat >$DOCDIR/api/scripts/common/${module}.rst <<-_EOF_ + $module + $underline + .. automodule:: lmi.scripts.common.$module + :members: + _EOF_ +done + +# Add commands api reference to api/scripts.rst +if [ $WITH_COMMANDS = 1 ]; then + if [ -z "$COMMANDS" ]; then + COMMANDS=`find $OPENLMI_SCRIPTS_DIR/commands \ + -mindepth 1 -maxdepth 1 -type d | sort | xargs basename -a` + fi + + for cmd in $COMMANDS; do + link="api/scripts/$cmd" + echo >>$DOCDIR/api/scripts.rst " ../scripts/commands/$cmd/python" + done +fi diff --git a/doc/src/scripts/Makefile b/doc/src/scripts/Makefile index f612dc7..d72592c 100644 --- a/doc/src/scripts/Makefile +++ b/doc/src/scripts/Makefile @@ -27,9 +27,6 @@ devindex: echo " devel/basics"; \ echo " devel/command-classes"; \ echo " devel/command-properties"; \ - if [ "$(BUILD)" == html -o "$(BUILD)" == rtd ]; then \ - echo " devel/api"; \ - fi; \ ) > development.rst
devel: @@ -46,7 +43,7 @@ ifeq ($(WITH_COMMANDS), 0) else ( \ for cmd in $(COMMANDS); do \ - printf " * :ref:`openlmi-scripts-$${cmd}`\n"; \ + printf " * :ref:`openlmi-scripts-$${cmd}-cmd`\n"; \ done; \ ) > $@ endif @@ -62,24 +59,13 @@ else mkdir commands echo "Usage and developer documentations for commands of *LMI metacommand*'s" >> $@ printf "\n.. toctree::\n" >> $@ - printf " :maxdepth: 2\n\n" >> $@ + printf " :maxdepth: 1\n\n" >> $@ find $(OPENLMI_SCRIPTS_DIR)/commands -mindepth 1 -maxdepth 1 -type d | sort | \ while read cmdpath; \ do \ cmd=$$(basename $$cmdpath); \ - printf " commands/$$cmd\n" >> $@; \ - ln -s "$${cmdpath}/doc" commands/$${cmd}_docdir; \ - title="$${cmd^} command"; \ - length=`echo "$$title" | wc -c`; \ - ( \ - printf ".. _openlmi-scripts-$${cmd}:\n\n"; \ - printf "$${title}\n"; \ - printf -- "!%.0s" `seq 2 $$length`; \ - printf "\n\n"; \ - printf ".. toctree::\n :maxdepth: 2\n\n"; \ - printf " $${cmd}_docdir/cmdline.rst\n"; \ - printf " $${cmd}_docdir/python\n\n"; \ - ) > commands/$${cmd}.rst; \ + printf " commands/$${cmd}/cmdline.rst\n" >> $@; \ + ln -s "$${cmdpath}/doc" commands/$${cmd}; \ done endif
diff --git a/doc/src/scripts/devel/Makefile b/doc/src/scripts/devel/Makefile index dc35ec2..92fd071 100644 --- a/doc/src/scripts/devel/Makefile +++ b/doc/src/scripts/devel/Makefile @@ -8,13 +8,7 @@ DSTFIGS := $(patsubst %.svg,%.png,$(SRCFIGS))
.PHONY: help clean html
-all: api.rst $(TUTORIAL_TARBALL) fig - -api.rst: gendoc.sh $(wildcard $(SRCDIR)/lmi/scripts/*.py \ - $(SRCDIR)/lmi/scripts/common/*.py \ - $(SRCDIR)/lmi/scripts/common/command/*.py \ - $(SRCDIR)/lmi/scripts/common/formatter/*.py) - ./gendoc.sh +all: $(TUTORIAL_TARBALL) fig
fig: $(DSTFIGS)
@@ -22,7 +16,7 @@ fig: $(DSTFIGS) convert $? $@
clean: - -rm -rf modules/ api.rst $(TUTORIAL_TARBALL) $(DSTFIGS) + -rm -rf $(TUTORIAL_TARBALL) $(DSTFIGS)
$(TUTORIAL_TARBALL): tar -czf $@ mylf diff --git a/doc/src/scripts/devel/gendoc.sh b/doc/src/scripts/devel/gendoc.sh deleted file mode 100755 index 9c9dd05..0000000 --- a/doc/src/scripts/devel/gendoc.sh +++ /dev/null @@ -1,75 +0,0 @@ -#!/bin/bash - -# -# Helper script to generate developer documentation in -# modules/ and api.rst -# - -TOPDIR=../../../.. -DOCDIR=$TOPDIR/doc/src/scripts/devel -SRCDIR=$TOPDIR/cli/lmi/scripts - -[ -e $DOCDIR/modules ] || mkdir $DOCDIR/modules - -function get_modules() { - find $SRCDIR -type f -a -name '*.py' | \ - sed 's:/__init__.py$::' | \ - grep -v "^${SRCDIR}/?$" | \ - grep -v '/_' | \ - sort -u -} - -function get_module_name() { - path=`sed -e "s:^.*${SRCDIR}/(.*)$:\1:" -e "s:/:.:g"` - basename -s .py "$path" -} - -function get_version_string() { - pushd $TOPDIR/cli >/dev/null - out=`python setup.py --version` - git_version=`git describe HEAD 2>/dev/null` - echo -n "``$out``" - if [ -n "$git_version" ]; then - echo ", git: ``$git_version``" - fi - popd >/dev/null -} - -# api.rst header -cat >$DOCDIR/api.rst <<_EOF_ -OpenLMI Scripts API -=================== - -This is a generated documentation form *OpenLMI Scripts* sources. - -Developer of script library will be interested in -:py:mod:`lmi.scripts.common` package providing useful functionality to -script development. - -Generated from version: $(get_version_string) - -.. only:: html - - **Contents:** - -.. toctree:: - :maxdepth: 2 - -_EOF_ - -# Generate modules/*.rst -for module_path in `get_modules`; do - module=`echo "$module_path" | get_module_name` - out=$module.rst - len=`echo $module| wc -c` - len=$(($len-1)) - underline="" - for i in `seq $len`; do underline="=$underline"; done - cat >$DOCDIR/modules/$out <<_EOF_ -$module -$underline -.. automodule:: lmi.scripts.$module - :members: -_EOF_ - echo >>$DOCDIR/api.rst " modules/$module" - done diff --git a/doc/src/shell/Makefile b/doc/src/shell/Makefile deleted file mode 100644 index 580245d..0000000 --- a/doc/src/shell/Makefile +++ /dev/null @@ -1,11 +0,0 @@ -SRCDIR ?= ../../../cli - -.PHONY: help clean html commands.rst - -all: code.rst - -code.rst: generate_code.py $(wildcard $(SRCDIR)/lmi/shell/*.py) - ./generate_code.py - -clean: - -rm -rf _code code.rst diff --git a/doc/src/shell/generate_code.py b/doc/src/shell/generate_code.py deleted file mode 100755 index 3b5925e..0000000 --- a/doc/src/shell/generate_code.py +++ /dev/null @@ -1,37 +0,0 @@ -#!/usr/bin/python - -import os -import sys - -mod_path = os.path.abspath("../../../cli/lmi/shell/") - -filt = lambda p: \ - p.endswith(".py") and \ - not p.startswith("_") and \ - p != "LMIShellVersion.py" -filenames = filter(filt, os.listdir(mod_path)) -filenames.sort() - -if not os.path.exists("_code"): - os.mkdir("_code") - -code_fout = open("code.rst", "w") -code_fout.write( - "API Documentation\n=================\n\n" - ".. toctree::\n" - " :maxdepth: 2\n\n") - -for filename in filenames: - module = str(filename[:-3]) - - code_fout.write(" _code/code_%s\n" % module) - - code_module_fout = open("_code/code_"+module+".rst", "w") - code_module_fout.write("%s Package\n" % module) - code_module_fout.write("=" * (len(module)+8) + "\n\n") - code_module_fout.write(".. automodule:: lmi.shell.%s\n" % module) - code_module_fout.write(" :members:\n") - code_module_fout.write(" :undoc-members:\n") - code_module_fout.close() - -code_fout.close()
cura-tools-devel@lists.fedorahosted.org