From 7c7e7f92b1997abd8bce552a00ce0a7d9b3c2dc4 Mon Sep 17 00:00:00 2001 From: Nicolas Sebrecht Date: Tue, 10 Mar 2015 05:19:59 +0100 Subject: [PATCH] website: learn to build the sphinx documentation Signed-off-by: Nicolas Sebrecht --- .gitignore | 1 + Makefile | 3 +- docs/Makefile | 3 + docs/conf.py | 201 +++++++++++++++++++++++++++++++++++++++++++ docs/doc-src/conf.py | 14 +-- docs/website-doc.sh | 37 ++++++++ get-website.sh | 9 +- 7 files changed, 259 insertions(+), 9 deletions(-) create mode 100644 docs/conf.py create mode 100755 docs/website-doc.sh diff --git a/.gitignore b/.gitignore index 235f5fa..cecdf30 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ /build/ *.pyc offlineimap.1 +offlineimapui.7 diff --git a/Makefile b/Makefile index c355583..bfe4523 100644 --- a/Makefile +++ b/Makefile @@ -35,7 +35,8 @@ clean: -find . -name '*.pygc' -exec rm -f {} \; -find . -name '*.class' -exec rm -f {} \; -find . -name '.cache*' -exec rm -f {} \; - -find . -name '*.html' -exec rm -f {} \; + # Care with that. We have html in subdirs we want to keep. + -find ./docs -name '*.html' -exec rm -f {} \; -rm -f manpage.links manpage.refs -find . -name auth -exec rm -vf {}/password {}/username \; @$(MAKE) -C docs clean diff --git a/docs/Makefile b/docs/Makefile index cd688f7..6063dc7 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -25,6 +25,9 @@ offlineimap.1: MANUAL.rst doc: $(SPHINXBUILD) -b html -d html/doctrees doc-src html +websitedoc: + ./website-doc.sh + clean: $(RM) -f $(HTML_TARGETS) $(RM) -f offlineimap.1 ../offlineimap.1 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..3f4bb6c --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,201 @@ +# -*- coding: utf-8 -*- +# +# pyDNS documentation build configuration file, created by +# sphinx-quickstart on Tue Feb 2 10:00:47 2010. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# 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('../..')) + +from offlineimap import __version__,__author__ +# -- 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 = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.viewcode'] +autoclass_content = "both" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'OfflineImap' +copyright = u'2002-2010, ' + __author__ + +# 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 = __version__ +# The full version, including alpha/beta/rc tags. +release = __version__ + +# 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 = [] + +# 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 = False + +# 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' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'default' +#html_style = '' +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# 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 = ['html'] + +# 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 = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +html_use_modindex = False + +# 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, links to the reST sources are added to the pages. +#html_show_sourcelink = 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 = 'dev-doc' + + +# -- 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, documentclass [howto/manual]). +latex_documents = [ + ('index', 'offlineimap.tex', u'OfflineImap Documentation', + u'OfflineImap contributors', '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 + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/doc-src/conf.py b/docs/doc-src/conf.py index 3f4bb6c..0886d4a 100644 --- a/docs/doc-src/conf.py +++ b/docs/doc-src/conf.py @@ -16,9 +16,9 @@ import sys, os # 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('../..')) -from offlineimap import __version__,__author__ +from offlineimap import __version__, __bigversion__, __author__, __copyright__ # -- General configuration ----------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be extensions @@ -40,8 +40,8 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'OfflineImap' -copyright = u'2002-2010, ' + __author__ +project = u'OfflineIMAP' +copyright = __copyright__ # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -50,7 +50,7 @@ copyright = u'2002-2010, ' + __author__ # The short X.Y version. version = __version__ # The full version, including alpha/beta/rc tags. -release = __version__ +release = __bigversion__ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -175,8 +175,8 @@ htmlhelp_basename = 'dev-doc' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'offlineimap.tex', u'OfflineImap Documentation', - u'OfflineImap contributors', 'manual'), + ('index', 'offlineimap.tex', u'OfflineIMAP Documentation', + u'OfflineIMAP contributors', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of diff --git a/docs/website-doc.sh b/docs/website-doc.sh new file mode 100755 index 0000000..f705b10 --- /dev/null +++ b/docs/website-doc.sh @@ -0,0 +1,37 @@ +#!/bin/sh +# +# vim: expandtab ts=2 : + +SPHINXBUILD=sphinx-build +TMPDIR='/tmp/offlineimap-sphinx-doctrees' +WEBSITE='../website' +DESTBASE="${WEBSITE}/_doc/versions" +VERSIONS_YML="${WEBSITE}/_data/versions.yml" + +version="v$(../offlineimap.py --version)" + +test -d "$DESTBASE" || exit 1 +dest="${DESTBASE}/${version}" + +# +# Build sphinx documentation. +# +echo "Cleaning target directory: $dest" +rm -rf "$dest" +$SPHINXBUILD -b html -d "$TMPDIR" doc-src "$dest" + +# +# Dynamically build JSON definitions for Jekyll. +# +echo "Building Jekyll data: $VERSIONS_YML" +for version in $(ls "$DESTBASE") +do + echo "- $version" +done > "$VERSIONS_YML" + +# +# Copy usefull sources of documentation. +# + +# User doc +for foo in ../Changelog.rst ../Changelog.maint.rst diff --git a/get-website.sh b/get-website.sh index fe6e9f7..74ec3d4 100755 --- a/get-website.sh +++ b/get-website.sh @@ -5,5 +5,12 @@ then echo "Directory 'website' already exists..." exit 1 else - git clone TODO + git clone https://github.com/OfflineIMAP/offlineimap.github.io.git +cat </offlineimap.github.io.git +EOF fi