From 2c1cacc0acfafcac4d6ffa200908d0649a3f571e Mon Sep 17 00:00:00 2001 From: Wojtek Porczyk Date: Fri, 21 Nov 2014 12:30:23 +0100 Subject: [PATCH] doc: swallow manpages into sphinx --- doc/Makefile | 184 +++++++++++++++--- doc/apidoc/Makefile | 153 --------------- doc/{apidoc => }/conf.py | 61 +++++- doc/{apidoc => }/index.rst | 17 +- doc/{apidoc => }/qubes-dochelpers.rst | 0 doc/{apidoc => }/qubes-events.rst | 0 doc/{apidoc => }/qubes-ext.rst | 0 doc/{apidoc => }/qubes-log.rst | 0 doc/{apidoc => }/qubes-plugins.rst | 0 doc/qubes-tools/index.rst | 8 + .../{qubes_guid.rst => qubes-guid.rst} | 26 +-- doc/qubes-tools/qubes-prefs.rst | 16 +- doc/{apidoc => }/qubes-vm/adminvm.rst | 0 doc/{apidoc => }/qubes-vm/appvm.rst | 0 doc/{apidoc => }/qubes-vm/dispvm.rst | 0 doc/{apidoc => }/qubes-vm/hvm.rst | 0 doc/{apidoc => }/qubes-vm/index.rst | 0 doc/{apidoc => }/qubes-vm/netvm.rst | 0 doc/{apidoc => }/qubes-vm/proxyvm.rst | 0 doc/{apidoc => }/qubes-vm/qubesvm.rst | 0 doc/{apidoc => }/qubes-vm/templatehvm.rst | 0 doc/{apidoc => }/qubes-vm/templatevm.rst | 0 doc/{apidoc => }/qubes.rst | 0 doc/qvm-tools/index.rst | 8 + doc/qvm-tools/qvm-add-appvm.rst | 39 ++-- doc/qvm-tools/qvm-add-template.rst | 34 ++-- doc/qvm-tools/qvm-backup-restore.rst | 57 ++++-- doc/qvm-tools/qvm-backup.rst | 26 +-- doc/qvm-tools/qvm-block.rst | 47 +++-- doc/qvm-tools/qvm-clone-template.rst | 29 +-- doc/qvm-tools/qvm-clone.rst | 30 +-- doc/qvm-tools/qvm-create-default-dvm.rst | 17 +- doc/qvm-tools/qvm-create.rst | 86 +++++--- doc/qvm-tools/qvm-firewall.rst | 76 +++++--- doc/qvm-tools/qvm-grow-private.rst | 22 +-- doc/qvm-tools/qvm-kill.rst | 22 +-- doc/qvm-tools/qvm-ls.rst | 54 +++-- doc/qvm-tools/qvm-pci.rst | 35 ++-- doc/qvm-tools/qvm-prefs.rst | 36 ++-- doc/qvm-tools/qvm-remove.rst | 34 ++-- doc/qvm-tools/qvm-revert-template-changes.rst | 26 +-- doc/qvm-tools/qvm-run.rst | 92 ++++++--- doc/qvm-tools/qvm-service.rst | 45 +++-- doc/qvm-tools/qvm-shutdown.rst | 54 ++--- doc/qvm-tools/qvm-start.rst | 42 ++-- doc/qvm-tools/qvm-template-commit.rst | 22 +-- rpm_spec/core-dom0-doc.spec | 2 +- 47 files changed, 805 insertions(+), 595 deletions(-) delete mode 100644 doc/apidoc/Makefile rename doc/{apidoc => }/conf.py (72%) rename doc/{apidoc => }/index.rst (59%) rename doc/{apidoc => }/qubes-dochelpers.rst (100%) rename doc/{apidoc => }/qubes-events.rst (100%) rename doc/{apidoc => }/qubes-ext.rst (100%) rename doc/{apidoc => }/qubes-log.rst (100%) rename doc/{apidoc => }/qubes-plugins.rst (100%) create mode 100644 doc/qubes-tools/index.rst rename doc/qubes-tools/{qubes_guid.rst => qubes-guid.rst} (53%) rename doc/{apidoc => }/qubes-vm/adminvm.rst (100%) rename doc/{apidoc => }/qubes-vm/appvm.rst (100%) rename doc/{apidoc => }/qubes-vm/dispvm.rst (100%) rename doc/{apidoc => }/qubes-vm/hvm.rst (100%) rename doc/{apidoc => }/qubes-vm/index.rst (100%) rename doc/{apidoc => }/qubes-vm/netvm.rst (100%) rename doc/{apidoc => }/qubes-vm/proxyvm.rst (100%) rename doc/{apidoc => }/qubes-vm/qubesvm.rst (100%) rename doc/{apidoc => }/qubes-vm/templatehvm.rst (100%) rename doc/{apidoc => }/qubes-vm/templatevm.rst (100%) rename doc/{apidoc => }/qubes.rst (100%) create mode 100644 doc/qvm-tools/index.rst diff --git a/doc/Makefile b/doc/Makefile index a8aec59c..95b72af8 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,30 +1,164 @@ -QVM_DIR=qvm-tools -QUBES_DIR=qubes-tools -PANDOC=pandoc -s -f rst -t man +# Makefile for Sphinx documentation +# -QVM_DOCS=$(patsubst %.rst,%.1.gz,$(wildcard $(QVM_DIR)/*.rst)) -QUBES_DOCS=$(patsubst %.rst,%.1.gz,$(wildcard $(QUBES_DIR)/*.rst)) +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# 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 clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: - @echo "make rst=example.rst preview -- generate manpage preview from example.rst" - @echo "make manpages -- generate manpages" - @echo "make install -- generate manpages and copy them to /usr/share/man" - -install: manpages - mkdir -p $(DESTDIR)/usr/share/man/man1 - cp $(QVM_DOCS) $(DESTDIR)/usr/share/man/man1/ - cp $(QUBES_DOCS) $(DESTDIR)/usr/share/man/man1/ - -%.1: %.rst - $(PANDOC) $< > $@ - -%.1.gz: %.1 - gzip -f $< - -manpages: $(QVM_DOCS) $(QUBES_DOCS) $(VM_DOCS) - -preview: $(rst) - pandoc -s -f rst -t man $(rst) | groff -mandoc -Tlatin1 | less -R + @echo "Please use \`make ' where 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 " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @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 " 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 " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo + @echo " install to generate manpages and copy them to \$$(DESTDIR)/usr/share/man" clean: - rm -f $(QVM_DOCS) $(QUBES_DOCS) $(VM_DOCS) + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +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: + $(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/core-admin.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/core-admin.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/core-admin" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/core-admin" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +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: + $(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." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + for file in $(BUILDDIR)/man/*.[12345678]; do \ + gzip -f $$file; \ + done + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +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: + $(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: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +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: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + + +.PHONY: install +install: man + mkdir -p $(DESTDIR)/usr/share/man/man1 + cp $(BUILDDIR)/man/* $(DESTDIR)/usr/share/man/man1/ diff --git a/doc/apidoc/Makefile b/doc/apidoc/Makefile deleted file mode 100644 index c46c8695..00000000 --- a/doc/apidoc/Makefile +++ /dev/null @@ -1,153 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# 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 clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where 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 " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @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 " 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 " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -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: - $(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/core-admin.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/core-admin.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/core-admin" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/core-admin" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -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: - $(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." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -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: - $(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: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -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: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/apidoc/conf.py b/doc/conf.py similarity index 72% rename from doc/apidoc/conf.py rename to doc/conf.py index 3a05d7ff..1a34519e 100644 --- a/doc/apidoc/conf.py +++ b/doc/conf.py @@ -19,7 +19,7 @@ import time # 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('../')) # -- General configuration ----------------------------------------------------- @@ -51,7 +51,7 @@ copyright = u'2010-{}, Invisible Things Lab'.format(time.strftime('%Y')) # built documents. # # The short X.Y version. -version = open('../../version').read() +version = open('../version').read().strip() # The full version, including alpha/beta/rc tags. release = subprocess.check_output(['git', 'describe', '--long', '--dirty']).strip() @@ -219,9 +219,62 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). + +# authors should be empty and authors should be specified in each man page, +# because html builder will omit them +_man_pages_author = [] + man_pages = [ - ('index', 'core-admin', u'core-admin Documentation', - [u'Invisible Things Lab'], 1) + ('qvm-tools/qvm-add-appvm', 'qvm-add-appvm', + u'Add an already installed appvm to the Qubes DB', _man_pages_author, 1), + ('qvm-tools/qvm-add-template', 'qvm-add-template', + u'Adds an already installed template to the Qubes DB', _man_pages_author, 1), + ('qvm-tools/qvm-backup-restore', 'qvm-backup-restore', + u'Restores Qubes VMs from backup', _man_pages_author, 1), + ('qvm-tools/qvm-backup', 'qvm-backup', + u'Create backup of specified VMs', _man_pages_author, 1), + ('qvm-tools/qvm-block', 'qvm-block', + u'List/set VM block devices.', _man_pages_author, 1), + ('qvm-tools/qvm-clone-template', 'qvm-clone-template', + u'Clones an existing template by copying all its disk files', _man_pages_author, 1), + ('qvm-tools/qvm-clone', 'qvm-clone', + u'Clones an existing VM by copying all its disk files', _man_pages_author, 1), + ('qvm-tools/qvm-create-default-dvm', 'qvm-create-default-dvm', + u'Creates a default disposable VM', _man_pages_author, 1), + ('qvm-tools/qvm-create', 'qvm-create', + u'Creates a new VM', _man_pages_author, 1), + ('qvm-tools/qvm-firewall', 'qvm-firewall', + u'Qubes firewall configuration', _man_pages_author, 1), + ('qvm-tools/qvm-grow-private', 'qvm-grow-private', + u'Increase private storage capacity of a specified VM', _man_pages_author, 1), + ('qvm-tools/qvm-kill', 'qvm-kill', + u'Kill the specified VM', _man_pages_author, 1), + ('qvm-tools/qvm-ls', 'qvm-ls', + u'List VMs and various information about them', _man_pages_author, 1), + ('qvm-tools/qvm-pci', 'qvm-pci', + u'List/set VM PCI devices', _man_pages_author, 1), + ('qvm-tools/qvm-prefs', 'qvm-prefs', + u'List/set various per-VM properties', _man_pages_author, 1), + ('qvm-tools/qvm-remove', 'qvm-remove', + u'Remove a VM', _man_pages_author, 1), + ('qvm-tools/qvm-revert-template-changes', 'qvm-revert-template-changes', + u'Revert changes to a template', _man_pages_author, 1), + ('qvm-tools/qvm-run', 'qvm-run', + u'Run a command on a specified VM', _man_pages_author, 1), + ('qvm-tools/qvm-service', 'qvm-service', + u'Manage (Qubes-specific) services started in VM', _man_pages_author, 1), + ('qvm-tools/qvm-shutdown', 'qvm-shutdown', + u'Gracefully shut down a VM', _man_pages_author, 1), + ('qvm-tools/qvm-start', 'qvm-start', + u'Start a specified VM', _man_pages_author, 1), + ('qvm-tools/qvm-template-commit', 'qvm-template-commit', + u'Commit changes to a template', _man_pages_author, 1), + + + ('qubes-tools/qubes-guid', 'qubes-guid', + u'Daemon for Qubes GUI isolation protocol', _man_pages_author, 1), + ('qubes-tools/qubes-prefs', 'qubes-prefs', + u'Display system-wide Qubes settings', _man_pages_author, 1), ] # If true, show URL addresses after external links. diff --git a/doc/apidoc/index.rst b/doc/index.rst similarity index 59% rename from doc/apidoc/index.rst rename to doc/index.rst index ec19628b..525a3d00 100644 --- a/doc/apidoc/index.rst +++ b/doc/index.rst @@ -6,7 +6,22 @@ Welcome to core-admin's documentation! ====================================== -Contents: +This page contains documentation autogenerated from source tree. It includes +manpages and API documentation. For primary user documentation, see +`https://wiki.qubes-os.org `_. + +User documentation +------------------ + +.. toctree:: + :maxdepth: 2 + :glob: + + qvm-tools/index + qubes-tools/index + +Developer documentation +----------------------- .. toctree:: :maxdepth: 2 diff --git a/doc/apidoc/qubes-dochelpers.rst b/doc/qubes-dochelpers.rst similarity index 100% rename from doc/apidoc/qubes-dochelpers.rst rename to doc/qubes-dochelpers.rst diff --git a/doc/apidoc/qubes-events.rst b/doc/qubes-events.rst similarity index 100% rename from doc/apidoc/qubes-events.rst rename to doc/qubes-events.rst diff --git a/doc/apidoc/qubes-ext.rst b/doc/qubes-ext.rst similarity index 100% rename from doc/apidoc/qubes-ext.rst rename to doc/qubes-ext.rst diff --git a/doc/apidoc/qubes-log.rst b/doc/qubes-log.rst similarity index 100% rename from doc/apidoc/qubes-log.rst rename to doc/qubes-log.rst diff --git a/doc/apidoc/qubes-plugins.rst b/doc/qubes-plugins.rst similarity index 100% rename from doc/apidoc/qubes-plugins.rst rename to doc/qubes-plugins.rst diff --git a/doc/qubes-tools/index.rst b/doc/qubes-tools/index.rst new file mode 100644 index 00000000..429b0bfa --- /dev/null +++ b/doc/qubes-tools/index.rst @@ -0,0 +1,8 @@ +System-wide tools +================= + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/doc/qubes-tools/qubes_guid.rst b/doc/qubes-tools/qubes-guid.rst similarity index 53% rename from doc/qubes-tools/qubes_guid.rst rename to doc/qubes-tools/qubes-guid.rst index d1b35790..61c6e4d8 100644 --- a/doc/qubes-tools/qubes_guid.rst +++ b/doc/qubes-tools/qubes-guid.rst @@ -1,22 +1,22 @@ -========== -qubes_guid -========== +.. program:: qubes-guid -NAME -==== -qubes_guid +================================================================ +:program:`qubes-guid` -- Daemon for Qubes GUI isolation protocol +================================================================ -:Date: 2012-04-13 - -SYNOPSIS +Synopsis ======== -| qubes_guid -d domain_id [-c color] [-l label_index] [-i icon name, no suffix] [-v] [-q] +| qubes-guid -d domain_id [-c color] [-l label_index] [-i icon name, no suffix] [-v] [-q] -OPTIONS +Options ======= --v + +.. option:: -v + Increase log verbosity --q + +.. option:: -q + Decrease log verbosity Log levels: diff --git a/doc/qubes-tools/qubes-prefs.rst b/doc/qubes-tools/qubes-prefs.rst index 0d4b6ca4..ca0a4eb3 100644 --- a/doc/qubes-tools/qubes-prefs.rst +++ b/doc/qubes-tools/qubes-prefs.rst @@ -1,10 +1,8 @@ -=========== -qubes-prefs -=========== +.. program:: qubes-prefs -NAME -==== -qubes-prefs - display system-wide Qubes settings, such as: +============================================================ +:program:`qubes-prefs` -- Display system-wide Qubes settings +============================================================ - clock VM - update VM @@ -13,13 +11,11 @@ qubes-prefs - display system-wide Qubes settings, such as: - default kernel - default netVM -:Date: 2012-04-13 - -SYNOPSIS +Synopsis ======== | qubes-prefs -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/apidoc/qubes-vm/adminvm.rst b/doc/qubes-vm/adminvm.rst similarity index 100% rename from doc/apidoc/qubes-vm/adminvm.rst rename to doc/qubes-vm/adminvm.rst diff --git a/doc/apidoc/qubes-vm/appvm.rst b/doc/qubes-vm/appvm.rst similarity index 100% rename from doc/apidoc/qubes-vm/appvm.rst rename to doc/qubes-vm/appvm.rst diff --git a/doc/apidoc/qubes-vm/dispvm.rst b/doc/qubes-vm/dispvm.rst similarity index 100% rename from doc/apidoc/qubes-vm/dispvm.rst rename to doc/qubes-vm/dispvm.rst diff --git a/doc/apidoc/qubes-vm/hvm.rst b/doc/qubes-vm/hvm.rst similarity index 100% rename from doc/apidoc/qubes-vm/hvm.rst rename to doc/qubes-vm/hvm.rst diff --git a/doc/apidoc/qubes-vm/index.rst b/doc/qubes-vm/index.rst similarity index 100% rename from doc/apidoc/qubes-vm/index.rst rename to doc/qubes-vm/index.rst diff --git a/doc/apidoc/qubes-vm/netvm.rst b/doc/qubes-vm/netvm.rst similarity index 100% rename from doc/apidoc/qubes-vm/netvm.rst rename to doc/qubes-vm/netvm.rst diff --git a/doc/apidoc/qubes-vm/proxyvm.rst b/doc/qubes-vm/proxyvm.rst similarity index 100% rename from doc/apidoc/qubes-vm/proxyvm.rst rename to doc/qubes-vm/proxyvm.rst diff --git a/doc/apidoc/qubes-vm/qubesvm.rst b/doc/qubes-vm/qubesvm.rst similarity index 100% rename from doc/apidoc/qubes-vm/qubesvm.rst rename to doc/qubes-vm/qubesvm.rst diff --git a/doc/apidoc/qubes-vm/templatehvm.rst b/doc/qubes-vm/templatehvm.rst similarity index 100% rename from doc/apidoc/qubes-vm/templatehvm.rst rename to doc/qubes-vm/templatehvm.rst diff --git a/doc/apidoc/qubes-vm/templatevm.rst b/doc/qubes-vm/templatevm.rst similarity index 100% rename from doc/apidoc/qubes-vm/templatevm.rst rename to doc/qubes-vm/templatevm.rst diff --git a/doc/apidoc/qubes.rst b/doc/qubes.rst similarity index 100% rename from doc/apidoc/qubes.rst rename to doc/qubes.rst diff --git a/doc/qvm-tools/index.rst b/doc/qvm-tools/index.rst new file mode 100644 index 00000000..6fb256c0 --- /dev/null +++ b/doc/qvm-tools/index.rst @@ -0,0 +1,8 @@ +VM manipulation tools +===================== + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/doc/qvm-tools/qvm-add-appvm.rst b/doc/qvm-tools/qvm-add-appvm.rst index 5fefab79..3ada1c79 100644 --- a/doc/qvm-tools/qvm-add-appvm.rst +++ b/doc/qvm-tools/qvm-add-appvm.rst @@ -1,29 +1,32 @@ -============= -qvm-add-appvm -============= +.. program:: qvm-add-appvm -NAME -==== -qvm-add-appvm - add an already installed appvm to the Qubes DB +========================================================================== +:program:`qvm-add-appvm` -- Add an already installed appvm to the Qubes DB +========================================================================== -WARNING: Noramlly you would not need this command, and you would use qvm-create instead! +.. warning:: + Normally you would not need this command, and you would use qvm-create instead! -:Date: 2012-04-10 - -SYNOPSIS +Synopsis ======== | qvm-add-appvm [options] -OPTIONS +Options ======= --h, --help - Show this help message and exit --p DIR_PATH, --path=DIR_PATH - Specify path to the template directory --c CONF_FILE, --conf=CONF_FILE - Specify the Xen VM .conf file to use(relative to the template dir path) -AUTHORS +.. option:: --help, -h + + Show this help message and exit + +.. option:: --path=DIR_PATH, -p DIR_PATH + + Specify path to the template directory + +.. option:: --conf=CONF_FILE, -c CONF_FILE + + Specify the Xen VM .conf file to use (relative to the template dir path) + +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-add-template.rst b/doc/qvm-tools/qvm-add-template.rst index 21961d58..1bf889f0 100644 --- a/doc/qvm-tools/qvm-add-template.rst +++ b/doc/qvm-tools/qvm-add-template.rst @@ -1,29 +1,33 @@ -================ -qvm-add-template -================ +.. program:: qvm-add-template -NAME -==== -qvm-add-template - adds an already installed template to the Qubes DB +================================================================================= +:program:`qvm-add-template` -- Adds an already installed template to the Qubes DB +================================================================================= -:Date: 2012-04-10 - -SYNOPSIS +Synopsis ======== | qvm-add-template [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit --p DIR_PATH, --path=DIR_PATH + +.. option:: --path=DIR_PATH, -p DIR_PATH + Specify path to the template directory --c CONF_FILE, --conf=CONF_FILE + +.. option:: --conf=CONF_FILE, -c CONF_FILE + Specify the Xen VM .conf file to use(relative to the template dir path) ---rpm + +.. option:: --rpm + Template files have been installed by RPM -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-backup-restore.rst b/doc/qvm-tools/qvm-backup-restore.rst index e078f7fa..c2f6db75 100644 --- a/doc/qvm-tools/qvm-backup-restore.rst +++ b/doc/qvm-tools/qvm-backup-restore.rst @@ -1,39 +1,54 @@ -================== -qvm-backup-restore -================== +.. program:: qvm-backup-restore -NAME -==== -qvm-backup-restore - restores Qubes VMs from backup +=============================================================== +:program:`qvm-backup-restore` -- Restores Qubes VMs from backup +=============================================================== -:Date: 2012-04-10 - -SYNOPSIS +Synopsis ======== | qvm-backup-restore [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit ---skip-broken + +.. option:: --skip-broken + Do not restore VMs that have missing templates or netvms ---ignore-missing + +.. option:: --ignore-missing + Ignore missing templates or netvms, restore VMs anyway ---skip-conflicting + +.. option:: --skip-conflicting + Do not restore VMs that are already present on the host ---force-root + +.. option:: --force-root + Force to run, even with root privileges ---replace-template=REPLACE_TEMPLATE - Restore VMs using another template, syntax: old-template-name:new-template-name (might be repeated) --x EXCLUDE, --exclude=EXCLUDE + +.. option:: --replace-template=REPLACE_TEMPLATE + + Restore VMs using another template, syntax: + ``old-template-name:new-template-name`` (might be repeated) + +.. option:: --exclude=EXCLUDE, -x EXCLUDE + Skip restore of specified VM (might be repeated) ---skip-dom0-home + +.. option:: --skip-dom0-home + Do not restore dom0 user home dir ---ignore-username-mismatch + +.. option:: --ignore-username-mismatch + Ignore dom0 username mismatch while restoring homedir -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-backup.rst b/doc/qvm-tools/qvm-backup.rst index 9d4dba8e..a0987caa 100644 --- a/doc/qvm-tools/qvm-backup.rst +++ b/doc/qvm-tools/qvm-backup.rst @@ -1,25 +1,25 @@ -========== -qvm-backup -========== +.. program:: qvm-backup -NAME -==== -qvm-backup +======================================================= +:program:`qvm-backup` -- Create backup of specified VMs +======================================================= -:Date: 2012-04-10 - -SYNOPSIS +Synopsis ======== | qvm-backup [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit --x EXCLUDE_LIST, --exclude=EXCLUDE_LIST + +.. option:: --exclude=EXCLUDE_LIST, -x EXCLUDE_LIST + Exclude the specified VM from backup (might be repeated) -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-block.rst b/doc/qvm-tools/qvm-block.rst index 839cfc6d..d637709e 100644 --- a/doc/qvm-tools/qvm-block.rst +++ b/doc/qvm-tools/qvm-block.rst @@ -1,15 +1,10 @@ -========= -qvm-block -========= +.. program:: qvm-block -NAME -==== -qvm-block - list/set VM PCI devices. +=============================================== +:program:`qvm-block` -- List/set VM PCI devices +=============================================== - -:Date: 2012-04-10 - -SYNOPSIS +Synopsis ======== | qvm-block -l [options] | qvm-block -a [options] @@ -17,24 +12,38 @@ SYNOPSIS | qvm-block -d [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit --l, --list + +.. option:: --list, -l + List block devices --a, --attach + +.. option:: --attach, -a + Attach block device to specified VM --d, --detach + +.. option:: --detach, -d + Detach block device --f FRONTEND, --frontend=FRONTEND + +.. option:: --frontend=FRONTEND, -f FRONTEND + Specify device name at destination VM [default: xvdi] ---ro + +.. option:: --ro + Force read-only mode ---no-auto-detach + +.. option:: --no-auto-detach + Fail when device already connected to other VM -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-clone-template.rst b/doc/qvm-tools/qvm-clone-template.rst index b7808059..112181e4 100644 --- a/doc/qvm-tools/qvm-clone-template.rst +++ b/doc/qvm-tools/qvm-clone-template.rst @@ -1,27 +1,28 @@ -================== -qvm-clone-template -================== +.. program:: qvm-clone-template -NAME -==== -qvm-clone-template - clones an existing template by copying all its disk files +========================================================================================== +:program:`qvm-clone-template` -- Clones an existing template by copying all its disk files +========================================================================================== -:Date: 2012-04-10 - -SYNOPSIS +Synopsis ======== | qvm-clone-template [options] -OPTIONS +Options ======= --h, --help +.. option:: --help, -h + Show this help message and exit --q, --quiet + +.. option:: --quiet, -q + Be quiet --p DIR_PATH, --path=DIR_PATH + +.. option:: --path=DIR_PATH, -p DIR_PATH + Specify path to the template directory -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-clone.rst b/doc/qvm-tools/qvm-clone.rst index 548a683f..d75682af 100644 --- a/doc/qvm-tools/qvm-clone.rst +++ b/doc/qvm-tools/qvm-clone.rst @@ -1,27 +1,29 @@ -========= -qvm-clone -========= +.. program:: qvm-clone -NAME -==== -qvm-clone - clones an existing VM by copying all its disk files +=========================================================================== +:program:`qvm-clone` -- Clones an existing VM by copying all its disk files +=========================================================================== -:Date: 2012-04-10 - -SYNOPSIS +Synopsis ======== | qvm-clone [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit --q, --quiet + +.. option:: --quiet, -q + Be quiet --p DIR_PATH, --path=DIR_PATH + +.. option:: --path=DIR_PATH, -p DIR_PATH + Specify path to the template directory -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-create-default-dvm.rst b/doc/qvm-tools/qvm-create-default-dvm.rst index b63fdb6f..046fb768 100644 --- a/doc/qvm-tools/qvm-create-default-dvm.rst +++ b/doc/qvm-tools/qvm-create-default-dvm.rst @@ -1,14 +1,10 @@ -====================== -qvm-create-default-dvm -====================== +.. program:: qvm-create-default-dvm -NAME -==== -qvm-create-default-dvm - creates a default disposable VM +==================================================================== +:program:`qvm-create-default-dvm` -- Creates a default Disposable VM +==================================================================== -:Date: 2012-04-10 - -SYNOPSIS +Synopsis ======== | qvm-create-default-dvm templatename|--default-template|--used-template [script-name|--default-script] @@ -29,8 +25,7 @@ templatename --default-script Use default script for seeding DispVM home. - -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-create.rst b/doc/qvm-tools/qvm-create.rst index 8da05414..8c54428a 100644 --- a/doc/qvm-tools/qvm-create.rst +++ b/doc/qvm-tools/qvm-create.rst @@ -1,53 +1,79 @@ -========== -qvm-create -========== +.. program:: qvm-create -NAME -==== -qvm-create - creates a new VM +========================================= +:program:`qvm-create` -- Creates a new VM +========================================= -:Date: 2012-04-10 - -SYNOPSIS +Synopsis ======== | qvm-create [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit --t TEMPLATE, --template=TEMPLATE + +.. option:: --template=TEMPLATE, -t TEMPLATE + Specify the TemplateVM to use --l LABEL, --label=LABEL + +.. option:: --label=LABEL, -l LABEL + Specify the label to use for the new VM (e.g. red, yellow, green, ...) --p, --proxy + +.. option:: --proxy, -p + Create ProxyVM --n, --net + +.. option:: --net, -n + Create NetVM --H, --hvm - Create HVM (standalone, unless --template option used) ---hvm-template + +.. option:: --hvm, -H + + Create HVM (standalone, unless :option:`--template` option used) + +.. option:: --hvm-template + Create HVM template --R ROOT_MOVE, --root-move-from=ROOT_MOVE + +.. option:: --root-move-from=ROOT_MOVE, -R ROOT_MOVE + Use provided root.img instead of default/empty one - (file will be MOVED) --r ROOT_COPY, --root-copy-from=ROOT_COPY + (file will be *moved*) + +.. option:: --root-copy-from=ROOT_COPY, -r ROOT_COPY + Use provided root.img instead of default/empty one - (file will be COPIED) --s, --standalone - Create standalone VM - independent of template --m MEM, --mem=MEM + (file will be *copied*) + +.. option:: --standalone, -s + + Create standalone VM --- independent of template + +.. option:: --mem=MEM, -m MEM + Initial memory size (in MB) --c VCPUS, --vcpus=VCPUS + +.. option:: --vcpus=VCPUS, -c VCPUS + VCPUs count --i, --internal + +.. option:: --internal, -i + Create VM for internal use only (hidden in qubes-manager, no appmenus) ---force-root + +.. option:: --force-root + Force to run, even with root privileges --q, --quiet + +.. option:: --quiet, -q + Be quiet -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-firewall.rst b/doc/qvm-tools/qvm-firewall.rst index 903da725..53837e90 100644 --- a/doc/qvm-tools/qvm-firewall.rst +++ b/doc/qvm-tools/qvm-firewall.rst @@ -1,14 +1,10 @@ -============ -qvm-firewall -============ +.. program:: qvm-firewall -NAME -==== -qvm-firewall +======================================================= +:program:`qvm-firewall` -- Qubes firewall configuration +======================================================= -:Date: 2012-04-10 - -SYNOPSIS +Synopsis ======== | qvm-firewall [-n] [action] [rule spec] @@ -17,29 +13,49 @@ Rule specification can be one of: 2. address|hostname[/netmask] tcp|udp service_name 3. address|hostname[/netmask] any -OPTIONS +Options ======= --h, --help - Show this help message and exit --l, --list - List firewall settings (default action) --a, --add - Add rule --d, --del - Remove rule (given by number or by rule spec) --P SET_POLICY, --policy=SET_POLICY - Set firewall policy (allow/deny) --i SET_ICMP, --icmp=SET_ICMP - Set ICMP access (allow/deny) --D SET_DNS, --dns=SET_DNS - Set DNS access (allow/deny) --Y SET_YUM_PROXY, --yum-proxy=SET_YUM_PROXY - Set access to Qubes yum proxy (allow/deny). - *Note:* if set to "deny", access will be rejected even if policy set to "allow" --n, --numeric - Display port numbers instead of services (makes sense only with --list) -AUTHORS +.. option:: --help, -h + + Show this help message and exit + +.. option:: --list, -l + + List firewall settings (default action) + +.. option:: --add, -a + + Add rule + +.. option:: --del, -d + + Remove rule (given by number or by rule spec) + +.. option:: --policy=SET_POLICY, -P SET_POLICY + + Set firewall policy (allow/deny) + +.. option:: --icmp=SET_ICMP, -i SET_ICMP + + Set ICMP access (allow/deny) + +.. option:: --dns=SET_DNS, -D SET_DNS + + Set DNS access (allow/deny) + +.. option:: --yum-proxy=SET_YUM_PROXY, -Y SET_YUM_PROXY + + Set access to Qubes yum proxy (allow/deny). + + .. note:: + if set to "deny", access will be rejected even if policy set to "allow" + +.. option:: --numeric, -n + + Display port numbers instead of services (makes sense only with :option:`--list`) + +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-grow-private.rst b/doc/qvm-tools/qvm-grow-private.rst index 9ac1c66e..33cb381c 100644 --- a/doc/qvm-tools/qvm-grow-private.rst +++ b/doc/qvm-tools/qvm-grow-private.rst @@ -1,23 +1,21 @@ -================ -qvm-grow-private -================ +.. program:: qvm-grow-private -NAME -==== -qvm-grow-private - increase private storage capacity of a specified VM +================================================================================== +:program:`qvm-grow-private` -- Increase private storage capacity of a specified VM +================================================================================== -:Date: 2012-04-10 - -SYNOPSIS +Synopsis ======== | qvm-grow-private -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-kill.rst b/doc/qvm-tools/qvm-kill.rst index 9c14f134..8bdf74a9 100644 --- a/doc/qvm-tools/qvm-kill.rst +++ b/doc/qvm-tools/qvm-kill.rst @@ -1,24 +1,22 @@ -======== -qvm-kill -======== +.. program:: qvm-kill -NAME -==== -qvm-kill - kills the specified VM +============================================ +:program:`qvm-kill` -- Kill the specified VM +============================================ -:Date: 2012-04-10 - -SYNOPSIS +Synopsis ======== | qvm-kill [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-ls.rst b/doc/qvm-tools/qvm-ls.rst index 2abbd9bc..c8f334aa 100644 --- a/doc/qvm-tools/qvm-ls.rst +++ b/doc/qvm-tools/qvm-ls.rst @@ -1,39 +1,53 @@ -====== -qvm-ls -====== +.. program:: qvm-ls -NAME -==== -qvm-ls - list VMs and various information about their state +================================================================ +:program:`qvm-ls` -- List VMs and various information about them +================================================================ -:Date: 2012-04-03 - -SYNOPSIS +Synopsis ======== | qvm-ls [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show help message and exit --n, --network + +.. option:: --network, -n + Show network addresses assigned to VMs --c, --cpu + +.. option:: --cpu, -c + Show CPU load --m, --mem + +.. option:: --mem, -m + Show memory usage --d, --disk + +.. option:: --disk, -d + Show VM disk utilization statistics --i, --ids + +.. option:: --ids, -i + Show Qubes and Xen id --k, --kernel + +.. option:: --kernel, -k + Show VM kernel options --b, --last-backup + +.. option:: --last-backup, -b + Show date of last VM backup ---raw-list + +.. option:: --raw-list + List only VM names one per line -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-pci.rst b/doc/qvm-tools/qvm-pci.rst index c2e667f8..72a9f4be 100644 --- a/doc/qvm-tools/qvm-pci.rst +++ b/doc/qvm-tools/qvm-pci.rst @@ -1,32 +1,35 @@ -======= -qvm-pci -======= +.. program:: qvm-pci -NAME -==== -qvm-pci - list/set VM PCI devices +============================================= +:program:`qvm-pci` -- List/set VM PCI devices +============================================= - -:Date: 2012-04-11 - -SYNOPSIS +Synopsis ======== | qvm-pci -l [options] | qvm-pci -a [options] | qvm-pci -d [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit --l, --list + +.. option:: --list, -l + List VM PCI devices --a, --add + +.. option:: --add, -a + Add a PCI device to specified VM --d, --delete + +.. option:: --delete, -d + Remove a PCI device from specified VM -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-prefs.rst b/doc/qvm-tools/qvm-prefs.rst index 197ef6eb..2aa5a548 100644 --- a/doc/qvm-tools/qvm-prefs.rst +++ b/doc/qvm-tools/qvm-prefs.rst @@ -1,32 +1,36 @@ -========= -qvm-prefs -========= +.. program:: qvm-prefs -NAME -==== -qvm-prefs - list/set various per-VM properties +========================================================== +:program:`qvm-prefs` -- List/set various per-VM properties +========================================================== -:Date: 2012-04-11 - -SYNOPSIS +Synopsis ======== | qvm-prefs -l [options] | qvm-prefs -g [options] | qvm-prefs -s [options] [...] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit --l, --list + +.. option:: --list, -l + List properties of a specified VM --g, --get + +.. option:: --get, -g + Get a single property of a specified VM --s, --set + +.. option:: --set, -s + Set properties of a specified VM -PROPERTIES +Properties ========== include_in_backups @@ -141,7 +145,7 @@ timezone Set emulated HVM clock timezone. Use ``localtime`` (the default) to use the same time as dom0 have. Note that HVM will get only clock value, not the timezone itself, so if you use ``localtime`` setting, OS inside of HVM should also be configured to treat hardware clock as local time (and have proper timezone set). -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-remove.rst b/doc/qvm-tools/qvm-remove.rst index b3a71aae..0db927e3 100644 --- a/doc/qvm-tools/qvm-remove.rst +++ b/doc/qvm-tools/qvm-remove.rst @@ -1,29 +1,33 @@ -========== -qvm-remove -========== +.. program:: qvm-remove -NAME -==== -qvm-remove - remove a VM +==================================== +:program:`qvm-remove` -- Remove a VM +==================================== -:Date: 2012-04-11 - -SYNOPSIS +Synopsis ======== | qvm-remove [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit --q, --quiet + +.. option:: --quiet, -q + Be quiet ---just-db + +.. option:: --just-db + Remove only from the Qubes Xen DB, do not remove any files ---force-root + +.. option:: --force-root + Force to run, even with root privileges -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-revert-template-changes.rst b/doc/qvm-tools/qvm-revert-template-changes.rst index f250cda2..5de5192c 100644 --- a/doc/qvm-tools/qvm-revert-template-changes.rst +++ b/doc/qvm-tools/qvm-revert-template-changes.rst @@ -1,25 +1,25 @@ -=========================== -qvm-revert-template-changes -=========================== +.. program:: qvm-revert-template-changes -NAME -==== -qvm-revert-template-changes +====================================================================== +:program:`qvm-revert-template-changes` -- Revert changes to a template +====================================================================== -:Date: 2012-04-11 - -SYNOPSIS +Synopsis ======== | qvm-revert-template-changes [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit ---force + +.. option:: --force + Do not prompt for comfirmation -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-run.rst b/doc/qvm-tools/qvm-run.rst index 15eb6779..1a7830d1 100644 --- a/doc/qvm-tools/qvm-run.rst +++ b/doc/qvm-tools/qvm-run.rst @@ -1,49 +1,79 @@ -======= -qvm-run -======= +.. program:: qvm-run -NAME -==== -qvm-run - run a command on a specified VM +===================================================== +:program:`qvm-run` -- Run a command on a specified VM +===================================================== -:Date: 2012-04-11 - -SYNOPSIS +Synopsis ======== | qvm-run [options] [] [] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit --q, --quiet + +.. option:: --quiet, -q + Be quiet --a, --auto + +.. option:: --auto, -a + Auto start the VM if not running --u USER, --user=USER + +.. option:: --user=USER, -u USER + Run command in a VM as a specified user ---tray + +.. option:: --tray + Use tray notifications instead of stdout ---all - Run command on all currently running VMs (or all paused, in case of --unpause) ---exclude=EXCLUDE_LIST - When --all is used: exclude this VM name (might be repeated) ---wait + +.. option:: --all + + Run command on all currently running VMs (or all paused, in case of :option:`--unpause`) + +.. option:: --exclude=EXCLUDE_LIST + + When :option:`--all` is used: exclude this VM name (might be repeated) + +.. option:: --wait + Wait for the VM(s) to shutdown ---shutdown - (deprecated) Do 'xl shutdown' for the VM(s) (can be combined this with --all and --wait) ---pause - Do 'xl pause' for the VM(s) (can be combined this with --all and --wait) ---unpause - Do 'xl unpause' for the VM(s) (can be combined this with --all and --wait) --p, --pass-io + +.. option:: --shutdown + + Do 'xl shutdown' for the VM(s) (can be combined with :option:`--all` and + :option:`--wait`) + + .. deprecated:: R2 + Use :manpage:`qvm-shutdown(1)` instead. + +.. option:: --pause + + Do 'xl pause' for the VM(s) (can be combined with :option:`--all` and + :option:`--wait`) + +.. option:: --unpause + + Do 'xl unpause' for the VM(s) (can be combined with :option:`--all` and + :option:`--wait`) + +.. option:: --pass-io, -p + Pass stdin/stdout/stderr from remote program ---localcmd=LOCALCMD - With --pass-io, pass stdin/stdout/stderr to the given program ---force + +.. option:: --localcmd=LOCALCMD + + With :option:`--pass-io`, pass stdin/stdout/stderr to the given program + +.. option:: --force + Force operation, even if may damage other VMs (eg. shutdown of NetVM) -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-service.rst b/doc/qvm-tools/qvm-service.rst index 3a552b07..82377156 100644 --- a/doc/qvm-tools/qvm-service.rst +++ b/doc/qvm-tools/qvm-service.rst @@ -1,33 +1,44 @@ -=========== -qvm-service -=========== +.. program:: qvm-service + +======================================================================== +:program:`qvm-service` -- Manage (Qubes-specific) services started in VM +======================================================================== NAME ==== -qvm-service - manage (Qubes-specific) services started in VM +qvm-service - :Date: 2012-05-30 -SYNOPSIS +Synopsis ======== | qvm-service [-l] | qvm-service [-e|-d|-D] -OPTIONS +Options ======= --h, --help +.. option:: --help, -h + Show this help message and exit --l, --list + +.. option:: --list, -l + List services (default action) --e, --enable + +.. option:: --enable, -e + Enable service --d, --disable + +.. option:: --disable, -d + Disable service --D, --default + +.. option:: --default, -D + Reset service to its default state (remove from the list). Default state means "lets VM choose" and can depend on VM type (NetVM, AppVM etc). -SUPPORTED SERVICES +Supported services ================== This list can be incomplete as VM can implement any additional service without knowlege of qubes-core code. @@ -109,9 +120,11 @@ updates-proxy-setup Setup yum at startup to use qubes-yum-proxy service. - *Note:* this service is automatically enabled when you allow VM to access - yum proxy (in firewall settings) and disabled when you deny access to yum - proxy. + .. note:: + + this service is automatically enabled when you allow VM to access yum + proxy (in firewall settings) and disabled when you deny access to yum + proxy. disable-default-route Default: disabled @@ -128,7 +141,7 @@ disable-dns-server The functionality is implemented in /usr/lib/qubes/setup-ip. -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-shutdown.rst b/doc/qvm-tools/qvm-shutdown.rst index d38fc4ea..4831c90a 100644 --- a/doc/qvm-tools/qvm-shutdown.rst +++ b/doc/qvm-tools/qvm-shutdown.rst @@ -1,33 +1,41 @@ -============ -qvm-shutdown -============ +.. program:: qvm-shutdown -NAME -==== -qvm-shutdown +==================================================== +:program:`qvm-shutdown` -- Gracefully shut down a VM +==================================================== -:Date: 2012-04-11 - -SYNOPSIS +Synopsis ======== | qvm-shutdown [options] -OPTIONS +Options ======= --h, --help - Show this help message and exit --q, --quiet - Be quiet ---force - Force operation, even if may damage other VMs (eg. shutdown of NetVM) ---wait - Wait for the VM(s) to shutdown ---all - Shutdown all running VMs ---exclude=EXCLUDE_LIST - When --all is used: exclude this VM name (might be repeated) -AUTHORS +.. option:: --help, -h + + Show this help message and exit + +.. option:: --quiet, -q + + Be quiet + +.. option:: --force + + Force operation, even if may damage other VMs (eg. shutdown of NetVM) + +.. option:: --wait + + Wait for the VM(s) to shutdown + +.. option:: --all + + Shutdown all running VMs + +.. option:: --exclude=EXCLUDE_LIST + + When :option:`--all` is used: exclude this VM name (might be repeated) + +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-start.rst b/doc/qvm-tools/qvm-start.rst index 3645b169..a880c0e1 100644 --- a/doc/qvm-tools/qvm-start.rst +++ b/doc/qvm-tools/qvm-start.rst @@ -1,33 +1,41 @@ -========= -qvm-start -========= +.. program:: qvm-start -NAME -==== -qvm-start - start a specified VM +============================================ +:program:`qvm-start` -- Start a specified VM +============================================ -:Date: 2012-04-11 - -SYNOPSIS +Synopsis ======== | qvm-start [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit --q, --quiet + +.. option:: --quiet, -q + Be quiet ---no-guid + +.. option:: --no-guid + Do not start the GUId (ignored) ---console + +.. option:: --console + Attach debugging console to the newly started VM ---dvm + +.. option:: --dvm + Do actions necessary when preparing DVM image ---custom-config=CUSTOM_CONFIG + +.. option:: --custom-config=CUSTOM_CONFIG + Use custom Xen config instead of Qubes-generated one -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/doc/qvm-tools/qvm-template-commit.rst b/doc/qvm-tools/qvm-template-commit.rst index bb2bf857..eb03bf6b 100644 --- a/doc/qvm-tools/qvm-template-commit.rst +++ b/doc/qvm-tools/qvm-template-commit.rst @@ -1,23 +1,21 @@ -=================== -qvm-template-commit -=================== +.. program:: qvm-template-commit -NAME -==== -qvm-template-commit +============================================================== +:program:`qvm-template-commit` -- Commit changes to a template +============================================================== -:Date: 2012-04-11 - -SYNOPSIS +Synopsis ======== | qvm-template-commit [options] -OPTIONS +Options ======= --h, --help + +.. option:: --help, -h + Show this help message and exit -AUTHORS +Authors ======= | Joanna Rutkowska | Rafal Wojtczuk diff --git a/rpm_spec/core-dom0-doc.spec b/rpm_spec/core-dom0-doc.spec index c4d6068d..e6694f5b 100644 --- a/rpm_spec/core-dom0-doc.spec +++ b/rpm_spec/core-dom0-doc.spec @@ -44,7 +44,7 @@ Provides: qubes-doc-dom0 The Qubes docs for dom0 tools %build -make manpages +make man %install