From: stefan Date: Thu, 12 Feb 2009 05:54:26 +0000 (+0000) Subject: Enhance documentation generation. X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=05a794c31b971ad6814dd3c51c79fe35e7415a7b;p=roundup.git Enhance documentation generation. git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/roundup/trunk@4124 57a73879-2fb5-44c3-a270-3262357dd7e2 --- diff --git a/doc/_static/style.css b/doc/_static/style.css new file mode 100644 index 0000000..55c48d9 --- /dev/null +++ b/doc/_static/style.css @@ -0,0 +1,109 @@ +/* layout*/ +body +{ + font-family: sans-serif, Arial, Helvetica; + background-color: white; + color: #333; + margin:0; + padding: 0 3em 0 14em; +} +body > .header { margin: 0 0 0 -14em;} +body > .footer { margin: 0 0 0 -14em; clear:both;} +body > .navigation +{ + margin-left: -14em; + width: 14em; + float: left; +} +body > .content +{ + width: 100%; + margin: 0; +} +body > .header > #searchbox { position: absolute; right: 1em; top: 1em;} + +/* style */ + +:link { color: #bb0000; text-decoration: none;} +:visited { color: #770000; text-decoration: none;} +a.toc-backref { color: #000000; } + +.header h1 { margin-left: 1em; } + +body +{ + font-family: sans-serif, Arial, Helvetica; + background-color: #f5f5f5; + color: #333; +} + +.menu +{ + margin-right: 1em; + padding: 2pt; + border: solid thin #dadada; + background-color:#ffffff; +} +.menu ul { list-style-type:none; padding: 0;} +.menu ul ul { padding-left: 1em;} +.menu li { border-top: solid thin #dadada;} +.menu li:first-child { border-top: none;} + +/* related */ + +div.related +{ + width: 100%; + font-size: 90%; +} +div.related-top { border-bottom: solid thin #dadada;} +div.related-bottom { border-top: solid thin #dadada;} + +div.related ul +{ + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { display: inline;} + +div.related li.right +{ + float: right; + margin-right: 5px; +} + +.footer +{ + font-size: small; + text-align: center; + color: lightgrey; +} + +.content +{ + padding: 1em; + border: solid thin #dadada; + background-color: #ffffff; +} + +/* This is a little hack to inject a 'news' block into the title + page without having to set up a custom directive. */ +#roundup-issue-tracker .note +{ + float: right; + width: auto; + border: solid thin #dadada; + background-color:#f5f5f5; + padding: 1em; + margin: 1em; +} +#roundup-issue-tracker .note .admonition-title { display: none; } + +table +{ + border-collapse: collapse; + border-spacing: 1px; + background-color: #fafafa; +} diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html new file mode 100644 index 0000000..61d352a --- /dev/null +++ b/doc/_templates/layout.html @@ -0,0 +1,166 @@ + + +{%- macro relbar(class) %} +
+ +
+{%- endmacro %} +{%- macro sidebar() %} + {%- block sidebartoc %} + {%- if display_toc %} +

{{ _('Table Of Contents') }}

+ {{ toc }} + {%- endif %} + {%- endblock %} + {%- block sidebarrel %} + {%- if prev %} +

{{ _('Previous topic') }}

+

{{ prev.title }}

+ {%- endif %} + {%- if next %} +

{{ _('Next topic') }}

+

{{ next.title }}

+ {%- endif %} + {%- endblock %} + {%- block sidebarsourcelink %} + {%- if show_source and has_source and sourcename %} +

{{ _('This Page') }}

+ + {%- endif %} + {%- endblock %} + {%- block sidebarsearch %} + {%- if pagename != "search" %} + + + {%- endif %} + {%- endblock %} +{%- endmacro %} + + + + + {{ metatags }} + {%- if builder != 'htmlhelp' %} + {%- set titlesuffix = " — " + docstitle|e %} + {%- endif %} + {{ title|striptags }}{{ titlesuffix }} + {%- if builder == 'web' %} + + {%- for link, type, title in page_links %} + + {%- endfor %} + {%- else %} + + + {%- endif %} + {%- if builder != 'htmlhelp' %} + + {%- for scriptfile in script_files %} + + {%- endfor %} + {%- if use_opensearch %} + + {%- endif %} + {%- if favicon %} + + {%- endif %} + {%- endif %} +{%- block linktags %} + {%- if hasdoc('about') %} + + {%- endif %} + + + {%- if hasdoc('copyright') %} + + {%- endif %} + + {%- if parents %} + + {%- endif %} + {%- if next %} + + {%- endif %} + {%- if prev %} + + {%- endif %} +{%- endblock %} +{%- block extrahead %} {% endblock %} + + +

Roundup

+ {%- if pagename != "search" %} + + + {%- endif %} +
+
+
+ {{ sidebar() }} +
+
+
+ {{ relbar('related-top') }} + {{ body }} + {{ relbar('related-bottom') }} +
+{%- block footer %} +
+ {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- else %} + {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- endif %} + {%- if show_source and has_source and sourcename %} +

{{ _('source') }}

+ {%- endif %} +
+{%- endblock %} + + diff --git a/doc/acknowledgements.txt b/doc/acknowledgements.txt new file mode 100644 index 0000000..9d2a2b5 --- /dev/null +++ b/doc/acknowledgements.txt @@ -0,0 +1,132 @@ +Acknowledgements +================ + +Go Ping, you rock! Also, go Common Ground, ekit.com and Bizar Software for +letting me implement this system on their time. + +Thanks also to the many people on the mailing list, in the sourceforge +project and those who just report bugs: +Thomas Arendsen Hein, +Nerijus Baliunas, +Anthony Baxter, +Marlon van den Berg, +Bo Berglund, +Stéphane Bidoul, +Cameron Blackwood, +Jeff Blaine, +Duncan Booth, +Seb Brezel, +J Alan Brogan, +Titus Brown, +Steve Byan, +Brett Cannon, +Godefroid Chapelle, +Roch'e Compaan, +Wil Cooley, +Joe Cooper, +Kelley Dagley, +Bruno Damour, +Bradley Dean, +Toby Dickenson, +Paul F. Dubois, +Eric Earnst, +Peter Eisentraut, +Andrew Eland, +Jeff Epler, +Tom Epperly, +Tamer Fahmy, +Vickenty Fesunov, +Hernan Martinez Foffani, +Stuart D. Gathman, +Martin Geisler, +Ajit George, +Frank Gibbons, +Johannes Gijsbers, +Gus Gollings, +Philipp Gortan, +Dan Grassi, +Robin Green, +Jason Grout, +Charles Groves, +Engelbert Gruber, +Bruce Guenter, +Tamás Gulácsi, +Thomas Arendsen Hein, +Juergen Hermann, +Tobias Herp, +Uwe Hoffmann, +Alex Holkner, +Tobias Hunger, +Simon Hyde, +Paul Jimenez, +Christophe Kalt, +Timo Kankare, +Brian Kelley, +James Kew, +Sheila King, +Michael Klatt, +Bastian Kleineidam, +Axel Kollmorgen, +Cedric Krier, +Detlef Lannert, +Andrey Lebedev, +Henrik Levkowetz, +David Linke, +Martin v. Löwis, +Fredrik Lundh, +Will Maier, +Ksenia Marasanova, +Georges Martin, +Gordon McMillan, +John F Meinel Jr, +Roland Meister, +Ulrik Mikaelsson, +John Mitchell, +Ramiro Morales, +Toni Mueller, +Stefan Niederhauser, +Truls E. Næss, +Patrick Ohly, +Luke Opperman, +Eddie Parker, +Will Partain, +Ewout Prangsma, +Marcus Priesch, +Bernhard Reiter, +Roy Rapoport, +John P. Rouillard, +Luke Ross, +Ollie Rutherfurd, +Toby Sargeant, +Giuseppe Scelsi, +Ralf Schlatterbeck, +Gregor Schmid, +Florian Schulze, +Klamer Schutte, +Dougal Scott, +Stefan Seefeld, +Jouni K Seppänen, +Jeffrey P Shell, +Dan Shidlovsky, +Joel Shprentz, +Terrel Shumway, +Emil Sit, +Alexander Smishlajev, +Nathaniel Smith, +Leonardo Soto, +Maciej Starzyk, +Mitchell Surface, +Anatoly T., +Jon C. Thomason +Mike Thompson, +Michael Twomey, +Karl Ulbrich, +Martin Uzak, +Darryl VanDorp, +J Vickroy, +Timothy J. Warren, +William (Wilk), +Tue Wennerberg, +Matt Wilbert, +Chris Withers, +Milan Zamazal. diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..9837f89 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,191 @@ +# -*- coding: utf-8 -*- +# +# Roundup documentation build configuration file, created by +# sphinx-quickstart on Tue Jan 20 17:33:20 2009. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# The contents of this file are pickled, so don't put values in the namespace +# that aren't pickleable (module imports are okay, they're removed automatically). +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If your extensions are in another directory, add it here. If the directory +# is relative to the documentation root, use os.path.abspath to make it +# absolute, like shown here. +#sys.path.append(os.path.abspath('.')) + +# General configuration +# --------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +#extensions = ['toctree'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.txt' + +# The encoding of source files. +#source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Roundup' +copyright = u'2009, Richard Jones' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.4' +# The full version, including alpha/beta/rc tags. +release = '1.4' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = ['.build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# Options for HTML output +# ----------------------- + +# The style sheet to use for HTML and HTML Help pages. A file of that name +# must exist either in Sphinx' static/ path, or in one of the custom paths +# given in html_static_path. +html_style = 'default.css' + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +html_collapse_toctree = True + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +html_add_permalinks = False + +# If false, no module index is generated. +#html_use_modindex = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, the reST sources are included in the HTML build as _sources/. +#html_copy_source = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Roundupdoc' + + +# Options for LaTeX output +# ------------------------ + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, document class [howto/manual]). +latex_documents = [ + ('docs/index', 'Roundup.tex', ur'Roundup Documentation', + ur'Richard Jones', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True diff --git a/doc/contact.txt b/doc/contact.txt new file mode 100644 index 0000000..4005b7b --- /dev/null +++ b/doc/contact.txt @@ -0,0 +1,22 @@ +Contact +======= + +For general support enquiries about usage, a mailing list is available: + + roundup-users@sourceforge.net + +If you've got a great idea for roundup, or have found a bug, please +submit an issue to the tracker at: + + http://sourceforge.net/tracker/?group_id=31577 + +For discussions about developing or enhancing roundup: + + roundup-devel@sourceforge.net + +The admin for this project is Richard Jones: + + richard@users.sourceforge.net + +but he should only be contacted directly when none of the +above avenues of contact are suitable. diff --git a/doc/customizing.txt b/doc/customizing.txt index 5273e80..dadd5ec 100644 --- a/doc/customizing.txt +++ b/doc/customizing.txt @@ -1,3 +1,5 @@ +:tocdepth: 2 + =================== Customising Roundup =================== diff --git a/doc/index.txt b/doc/index.txt index 93609bf..cc8cc60 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -5,192 +5,20 @@ Roundup: an Issue-Tracking System for Knowledge Workers Contents ======== -- Features__ -- Installation__ and Upgrading__ existing installs -- `Frequently Asked Questions`__ -- `User Guide`__ -- `Configuring and Customising Roundup`__ -- `Administering Roundup Trackers`__ -- `Roundup's Design`__ (original__) -- `Developing Roundup`__ -- `Roundup Tracker Templates`__ -- Contact_ -- Acknowledgements_ -- License_ - -__ features.html -__ installation.html -__ upgrading.html -__ FAQ.html -__ user_guide.html -__ customizing.html -__ admin_guide.html -__ design.html -__ spec.html -__ developers.html -__ tracker_templates.html - -Contact -======= - -For general support enquiries about usage, a mailing list is available: - - roundup-users@sourceforge.net - -If you've got a great idea for roundup, or have found a bug, please -submit an issue to the tracker at: - - http://sourceforge.net/tracker/?group_id=31577 - -For discussions about developing or enhancing roundup: - - roundup-devel@sourceforge.net - -The admin for this project is Richard Jones: - - richard@users.sourceforge.net - -but he should only be contacted directly when none of the -above avenues of contact are suitable. - - -Acknowledgements -================ - -Go Ping, you rock! Also, go Common Ground, ekit.com and Bizar Software for -letting me implement this system on their time. - -Thanks also to the many people on the mailing list, in the sourceforge -project and those who just report bugs: -Thomas Arendsen Hein, -Nerijus Baliunas, -Anthony Baxter, -Marlon van den Berg, -Bo Berglund, -Stéphane Bidoul, -Cameron Blackwood, -Jeff Blaine, -Duncan Booth, -Seb Brezel, -J Alan Brogan, -Titus Brown, -Steve Byan, -Brett Cannon, -Godefroid Chapelle, -Roch'e Compaan, -Wil Cooley, -Joe Cooper, -Kelley Dagley, -Bruno Damour, -Bradley Dean, -Toby Dickenson, -Paul F. Dubois, -Eric Earnst, -Peter Eisentraut, -Andrew Eland, -Jeff Epler, -Tom Epperly, -Tamer Fahmy, -Vickenty Fesunov, -Hernan Martinez Foffani, -Stuart D. Gathman, -Martin Geisler, -Ajit George, -Frank Gibbons, -Johannes Gijsbers, -Gus Gollings, -Philipp Gortan, -Dan Grassi, -Robin Green, -Jason Grout, -Charles Groves, -Engelbert Gruber, -Bruce Guenter, -Tamás Gulácsi, -Thomas Arendsen Hein, -Juergen Hermann, -Tobias Herp, -Uwe Hoffmann, -Alex Holkner, -Tobias Hunger, -Simon Hyde, -Paul Jimenez, -Christophe Kalt, -Timo Kankare, -Brian Kelley, -James Kew, -Sheila King, -Michael Klatt, -Bastian Kleineidam, -Axel Kollmorgen, -Cedric Krier, -Detlef Lannert, -Andrey Lebedev, -Henrik Levkowetz, -David Linke, -Martin v. Löwis, -Fredrik Lundh, -Will Maier, -Ksenia Marasanova, -Georges Martin, -Gordon McMillan, -John F Meinel Jr, -Roland Meister, -Ulrik Mikaelsson, -John Mitchell, -Ramiro Morales, -Toni Mueller, -Stefan Niederhauser, -Truls E. Næss, -Patrick Ohly, -Luke Opperman, -Eddie Parker, -Will Partain, -Ewout Prangsma, -Marcus Priesch, -Bernhard Reiter, -Roy Rapoport, -John P. Rouillard, -Luke Ross, -Ollie Rutherfurd, -Toby Sargeant, -Giuseppe Scelsi, -Ralf Schlatterbeck, -Gregor Schmid, -Florian Schulze, -Klamer Schutte, -Dougal Scott, -Stefan Seefeld, -Jouni K Seppänen, -Jeffrey P Shell, -Dan Shidlovsky, -Joel Shprentz, -Terrel Shumway, -Emil Sit, -Alexander Smishlajev, -Nathaniel Smith, -Leonardo Soto, -Maciej Starzyk, -Mitchell Surface, -Anatoly T., -Jon C. Thomason -Mike Thompson, -Michael Twomey, -Karl Ulbrich, -Martin Uzak, -Darryl VanDorp, -J Vickroy, -Timothy J. Warren, -William (Wilk), -Tue Wennerberg, -Matt Wilbert, -Chris Withers, -Milan Zamazal. - - - -License -======= - -See COPYING.txt in the software distribution for the licensing terms. - +.. toctree:: + :maxdepth: 2 + + features + installation + upgrading + FAQ + user_guide + customizing + admin_guide + spec + original design + developers + tracker_templates + contact + acknowledgements + license diff --git a/doc/license.txt b/doc/license.txt new file mode 100644 index 0000000..9bd6de4 --- /dev/null +++ b/doc/license.txt @@ -0,0 +1,5 @@ +License +======= + +See COPYING.txt in the software distribution for the licensing terms. + diff --git a/roundup/dist/__init__.py b/roundup/dist/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/roundup/dist/command/__init__.py b/roundup/dist/command/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/roundup/dist/command/build_doc.py b/roundup/dist/command/build_doc.py new file mode 100644 index 0000000..72537ce --- /dev/null +++ b/roundup/dist/command/build_doc.py @@ -0,0 +1,37 @@ +# +# Copyright (C) 2009 Stefan Seefeld +# All rights reserved. +# For license terms see the file COPYING.txt. +# + +import os, sys +from stat import * +import os.path +from shutil import * +import glob + +from distutils.command import build +from distutils.spawn import spawn, find_executable +from distutils.dep_util import newer, newer_group +from distutils.dir_util import copy_tree, remove_tree, mkpath +from distutils.file_util import copy_file +from distutils import sysconfig + +class build_doc(build.build): + """Defines the specific procedure to build roundup's documentation.""" + + description = "build documentation" + + def run(self): + """Run this command, i.e. do the actual document generation.""" + + sphinx = find_executable('sphinx-build') + if not sphinx: + self.warn("could not find sphinx-build in PATH") + self.warn("cannot build documentation") + return + + doc_dir = os.path.join('share', 'doc', 'roundup', 'html') + temp_dir = os.path.join(self.build_temp, 'doc') + cmd = [sphinx, '-d', temp_dir, 'doc', doc_dir] + spawn(cmd) diff --git a/setup.py b/setup.py index fd32103..f9fddac 100644 --- a/setup.py +++ b/setup.py @@ -18,6 +18,8 @@ # # $Id: setup.py,v 1.105 2008-09-01 01:58:32 richard Exp $ + +from roundup.dist.command.build_doc import build_doc from distutils.core import setup, Extension from distutils.util import get_platform from distutils.file_util import write_file @@ -37,6 +39,15 @@ if not hasattr(DistributionMetadata, 'classifiers'): from roundup import msgfmt +def include(d, e): + """Generate a pair of (directory, file-list) for installation. + + 'd' -- A directory + + 'e' -- A glob pattern""" + + return (d, [f for f in glob('%s/%s'%(d, e)) if os.path.isfile(f)]) + ############################################################################# ### Build script files ############################################################################# @@ -340,6 +351,9 @@ def main(): installdatafiles.append((os.path.dirname(_mo_file), [os.path.join("build", _mo_file)])) + # add docs + installdatafiles.append(include(os.path.join('share', 'doc', 'roundup', 'html'), '*')) + # perform the setup action from roundup import __version__ setup_args = { @@ -422,6 +436,7 @@ mysql and postgresql). # Override certain command classes with our own ones 'cmdclass': { + 'build_doc': build_doc, 'build_scripts': build_scripts_roundup, 'build_py': build_py_roundup, 'build': build_roundup,