Skip to content

Commit f7c5e33

Browse files
saschalucassaschalucas
committed
recreate basic sphinx-build infrastructure
This creates basic sphinx-build files, including the ReST-source already updated to current state (3.0beta1).
1 parent 96f0a08 commit f7c5e33

File tree

6 files changed

+344
-0
lines changed

6 files changed

+344
-0
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
docs.ganeti.org/__pycache__
2+
.buildinfo
3+
.doctrees/

‎README.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Website docs.ganeti.org
2+
=======================
3+
4+
This website is served by github pages using the root directory (master branch only). It contains a table listing all versions of Ganeti documentation so far (see `docs.ganeti.org/index.rst`). To transform this into HTML, run `gen_index.sh`.
5+
6+
All other content must be retrieved (copied) from configured and compiled Ganeti source:
7+
8+
* `docs/ganeti/<version>/html` from `configure --enable-manpages-in-doc` out of `doc/man-html/`
9+
* `docs/ganeti/<version>/man` from `man/*.html`
10+
* `docs/ganeti/<version>/api/py` from `doc/api/py`
11+
* `docs/ganeti/<version>/api/hs` from `doc/api/hs`

‎docs.ganeti.org/conf.py

+215
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Ganeti documentation build configuration file, created by
4+
# sphinx-quickstart on Tue Apr 14 13:23:20 2009.
5+
#
6+
# This file is execfile()d with the current directory set to its containing dir.
7+
#
8+
# Note that not all possible configuration values are present in this
9+
# autogenerated file.
10+
#
11+
# All configuration values have a default; values that are commented out
12+
# serve to show the default.
13+
14+
# -- General configuration -----------------------------------------------------
15+
16+
# If your documentation needs a minimal Sphinx version, state it here.
17+
needs_sphinx = "1.0"
18+
19+
# Add any Sphinx extension module names here, as strings. They can be extensions
20+
# coming with Sphinx (named "sphinx.ext.*") or your custom ones.
21+
extensions = [
22+
'sphinx_roles',
23+
]
24+
25+
# Add any paths that contain templates here, relative to this directory.
26+
templates_path = ["_templates"]
27+
28+
# The suffix of source filenames.
29+
source_suffix = '.rst'
30+
31+
# The encoding of source files.
32+
source_encoding = "utf-8"
33+
34+
# The master toctree document.
35+
master_doc = "index"
36+
37+
# General information about the project.
38+
project = "Ganeti"
39+
#copyright = "2006-2015 Google Inc., 2020 the Ganeti Community"
40+
41+
# The version info for the project you're documenting, acts as replacement for
42+
# |version| and |release|, also used in various other places throughout the
43+
# built documents.
44+
#
45+
# These next two will be passed via the command line, see the makefile
46+
# The short X.Y version
47+
#version = VERSION_MAJOR + "." + VERSION_MINOR
48+
# The full version, including alpha/beta/rc tags.
49+
#release = PACKAGE_VERSION
50+
51+
# The language for content autogenerated by Sphinx. Refer to documentation
52+
# for a list of supported languages.
53+
language = "en"
54+
55+
# There are two options for replacing |today|: either, you set today to some
56+
# non-false value, then it is used:
57+
#today = ""
58+
# Else, today_fmt is used as the format for a strftime call.
59+
#today_fmt = "%B %d, %Y"
60+
61+
# List of documents that shouldn't be included in the build.
62+
#unused_docs = []
63+
64+
# List of directories, relative to source directory, that shouldn't be searched
65+
# for source files.
66+
exclude_trees = [
67+
]
68+
69+
# The reST default role (used for this markup: `text`) to use for all documents.
70+
#default_role = None
71+
72+
# If true, "()" will be appended to :func: etc. cross-reference text.
73+
#add_function_parentheses = True
74+
75+
# If true, the current module name will be prepended to all description
76+
# unit titles (such as .. function::).
77+
#add_module_names = True
78+
79+
# If true, sectionauthor and moduleauthor directives will be shown in the
80+
# output. They are ignored by default.
81+
#show_authors = False
82+
83+
# The name of the Pygments (syntax highlighting) style to use.
84+
pygments_style = "sphinx"
85+
86+
# A list of ignored prefixes for module index sorting.
87+
#modindex_common_prefix = []
88+
89+
90+
# -- Options for HTML output ---------------------------------------------------
91+
92+
# The theme to use for HTML and HTML Help pages. See the documentation for
93+
# a list of builtin themes.
94+
html_theme = 'classic'
95+
96+
# Theme options are theme-specific and customize the look and feel of a theme
97+
# further. For a list of options available for each theme, see the
98+
# documentation.
99+
html_theme_options = {
100+
# Disable showing the sidebar. Defaults to 'false'
101+
'nosidebar': True,
102+
}
103+
104+
# Add any paths that contain custom themes here, relative to this directory.
105+
#html_theme_path = []
106+
107+
# The name for this set of Sphinx documents. If None, it defaults to
108+
# "<project> v<release> documentation".
109+
#html_title = None
110+
111+
# A shorter title for the navigation bar. Default is the same as html_title.
112+
#html_short_title = None
113+
114+
# The name of an image file (relative to this directory) to place at the top
115+
# of the sidebar.
116+
#html_logo = None
117+
118+
# The name of an image file (within the static path) to use as favicon of the
119+
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
120+
# pixels large.
121+
#html_favicon = None
122+
123+
# Add any paths that contain custom static files (such as style sheets) here,
124+
# relative to this directory. They are copied after the builtin static files,
125+
# so a file named "default.css" will overwrite the builtin "default.css".
126+
#html_static_path = ["css"]
127+
128+
#html_style = "style.css"
129+
130+
# If not "", a "Last updated on:" timestamp is inserted at every page bottom,
131+
# using the given strftime format.
132+
html_last_updated_fmt = "%b %d, %Y"
133+
134+
# If true, SmartyPants will be used to convert quotes and dashes to
135+
# typographically correct entities.
136+
#html_use_smartypants = True
137+
138+
# Custom sidebar templates, maps document names to template names.
139+
#html_sidebars = {}
140+
141+
# Additional templates that should be rendered to pages, maps page names to
142+
# template names.
143+
#html_additional_pages = {}
144+
145+
# If false, no module index is generated.
146+
html_use_modindex = False
147+
148+
# If false, no index is generated.
149+
html_use_index = False
150+
151+
# If true, the index is split into individual pages for each letter.
152+
#html_split_index = False
153+
154+
# If true, links to the reST sources are added to the pages.
155+
html_show_sourcelink = False
156+
157+
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
158+
html_show_sphinx = False
159+
160+
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
161+
html_show_copyright = False
162+
163+
# If true, an OpenSearch description file will be output, and all pages will
164+
# contain a <link> tag referring to it. The value of this option must be the
165+
# base URL from which the finished HTML is served.
166+
#html_use_opensearch = ""
167+
168+
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
169+
#html_file_suffix = ""
170+
171+
# Output file base name for HTML help builder.
172+
htmlhelp_basename = "Ganetidoc"
173+
174+
175+
# -- Options for LaTeX output --------------------------------------------------
176+
177+
# The paper size ("letter" or "a4").
178+
#latex_paper_size = "a4"
179+
180+
# The font size ("10pt", "11pt" or "12pt").
181+
#latex_font_size = "10pt"
182+
183+
# Grouping the document tree into LaTeX files. List of tuples
184+
# (source start file, target name, title, author, documentclass [howto/manual]).
185+
latex_documents = [
186+
("index", "Ganeti.tex", "Ganeti Documentation",
187+
"Google Inc.", "manual"),
188+
]
189+
190+
# The name of an image file (relative to this directory) to place at the top of
191+
# the title page.
192+
#latex_logo = None
193+
194+
# For "manual" documents, if this is true, then toplevel headings are parts,
195+
# not chapters.
196+
#latex_use_parts = False
197+
198+
# If true, show page references after internal links.
199+
#latex_show_pagerefs = False
200+
201+
# If true, show URL addresses after external links.
202+
#latex_show_urls = False
203+
204+
# Additional stuff for the LaTeX preamble.
205+
#latex_preamble = ""
206+
207+
# Documents to append as an appendix to all manuals.
208+
#latex_appendices = []
209+
210+
# If false, no module index is generated.
211+
latex_domain_indices = False
212+
213+
# We override the manpage role and sphinx issues a warning, which is treated as
214+
# error. Suppress role_add warnings to avoid FTBFS.
215+

‎docs.ganeti.org/index.rst

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
.. role:: green
2+
3+
.. raw:: html
4+
5+
<style>.green { background-color: #afa ; font-weight: bold; }</style>
6+
7+
Ganeti documentation
8+
====================
9+
10+
This page links to the online documentation for the Ganeti project.
11+
Select the link pointing to the resource you'd like to view.
12+
13+
+-------------------+-------------+------------------------+----------------------------------------------------+---------------------+
14+
| Status | Version | Documentation | API | Man pages |
15+
+===================+=============+========================+====================================================+=====================+
16+
| beta | 3.0 | :gdoc:`doc <3.0>` | :hapi:`Haskell <3.0>`, :papi:`Python <3.0>` | :man:`man <3.0>` |
17+
+-------------------+-------------+------------------------+----------------------------------------------------+---------------------+
18+
| discontinued/alpha| 2.18 | :gdoc:`doc <2.18>` | :hapi:`Haskell <2.18>`, :papi:`Python <2.18>` | :man:`man <2.18>` |
19+
+-------------------+-------------+------------------------+----------------------------------------------------+---------------------+
20+
| discontinued/beta | 2.17 | :gdoc:`doc <2.17>` | :hapi:`Haskell <2.17>`, :papi:`Python <2.17>` | :man:`man <2.17>` |
21+
+-------------------+-------------+------------------------+----------------------------------------------------+---------------------+
22+
| :green:`Stable` | **2.16** | :gdoc:`doc <2.16>` | :hapi:`Haskell <2.16>`, :papi:`Python <2.16>` | :man:`man <2.16>` |
23+
+-------------------+-------------+------------------------+----------------------------------------------------+---------------------+
24+
| | 2.15 | :gdoc:`doc <2.15>` | :hapi:`Haskell <2.15>`, :papi:`Python <2.15>` | :man:`man <2.15>` |
25+
| +-------------+------------------------+----------------------------------------------------+---------------------+
26+
| | 2.14 | :gdoc:`doc <2.14>` | :hapi:`Haskell <2.14>`, :papi:`Python <2.14>` | :man:`man <2.14>` |
27+
| +-------------+------------------------+----------------------------------------------------+---------------------+
28+
| | 2.13 | :gdoc:`doc <2.13>` | :hapi:`Haskell <2.13>`, :papi:`Python <2.13>` | :man:`man <2.13>` |
29+
| +-------------+------------------------+----------------------------------------------------+---------------------+
30+
| | 2.12 | :gdoc:`doc <2.12>` | :hapi:`Haskell <2.12>`, :papi:`Python <2.12>` | :man:`man <2.12>` |
31+
| +-------------+------------------------+----------------------------------------------------+---------------------+
32+
| | 2.11 | :gdoc:`doc <2.11>` | :hapi:`Haskell <2.11>`, :papi:`Python <2.11>` | :man:`man <2.11>` |
33+
| +-------------+------------------------+----------------------------------------------------+---------------------+
34+
| | 2.10 | :gdoc:`doc <2.10>` | :hapi:`Haskell <2.10>`, :papi:`Python <2.10>` | :man:`man <2.10>` |
35+
| +-------------+------------------------+----------------------------------------------------+---------------------+
36+
| | 2.9 | :gdoc:`doc <2.9>` | :hapi:`Haskell <2.9>`, :papi:`Python <2.9>` | :man:`man <2.9>` |
37+
| +-------------+------------------------+----------------------------------------------------+---------------------+
38+
| Unmaintained | 2.8 | :gdoc:`doc <2.8>` | :hapi:`Haskell <2.8>`, :papi:`Python <2.8>` | :man:`man <2.8>` |
39+
| +-------------+------------------------+----------------------------------------------------+---------------------+
40+
| | 2.7 | :gdoc:`doc <2.7>` | :hapi:`Haskell <2.7>`, :papi:`Python <2.7>` | :man:`man <2.7>` |
41+
| +-------------+------------------------+----------------------------------------------------+---------------------+
42+
| | 2.6 | :gdoc:`doc <2.6>` | :hapi:`Haskell <2.6>`, :papi:`Python <2.6>` | :man:`man <2.6>` |
43+
| +-------------+------------------------+----------------------------------------------------+---------------------+
44+
| | 2.5 | :gdoc:`doc <2.5>` | :hapi:`Haskell <2.5>`, :papi:`Python <2.5>` | :man:`man <2.5>` |
45+
| +-------------+------------------------+----------------------------------------------------+---------------------+
46+
| | 2.4 | :gdoc:`doc <2.4>` | :api:`Python <2.4>` | :man:`man <2.4>` |
47+
| +-------------+------------------------+----------------------------------------------------+---------------------+
48+
| | 2.3 | :gdoc:`doc <2.3>` | :api:`Python <2.3>` | :man:`man <2.3>` |
49+
| +-------------+------------------------+----------------------------------------------------+---------------------+
50+
| | 2.2 | :gdoc:`doc <2.2>` | :api:`Python <2.2>` | :man:`man <2.2>` |
51+
| +-------------+------------------------+----------------------------------------------------+---------------------+
52+
| | 2.1 | :gdoc:`doc <2.1>` | :papi:`Python <2.1>` | :man:`man <2.1>` |
53+
+-------------------+-------------+------------------------+----------------------------------------------------+---------------------+
54+
55+
The documentation for the external (deprecated) *htools* package is still
56+
available at the `Index of /htools.deprecated <htools.deprecated/>`_.

‎docs.ganeti.org/sphinx_roles.py

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
"""Sphinx extension for Ganeti documentation overview.
2+
3+
"""
4+
import re
5+
from docutils.parsers.rst.roles import set_classes
6+
from docutils import nodes
7+
8+
# Regular expression for role types in doc overview
9+
_OVW_RE = re.compile(r"^(?P<text>\w+)\s+<(?P<version>[\w\.]+)>$")
10+
11+
def _GenericRole(role, rawtext, text, lineno, inliner, options={}, content=[]):
12+
try:
13+
m = _OVW_RE.match(text)
14+
if not m:
15+
raise ValueError
16+
except ValueError:
17+
msg= inliner.reporter.error("reference '%s' does not match regular"
18+
" expression '%s'" % (text, _OVW_RE.pattern))
19+
prb = inliner.problematic(rawtext, rawtext, msg)
20+
return [prb], [msg]
21+
22+
linktext = m.group("text")
23+
version = m.group("version")
24+
# pint to the path belonging to role
25+
if role == 'gdoc':
26+
ref = 'docs/ganeti/' + version + '/html/index.html'
27+
elif role == 'hapi':
28+
ref = 'docs/ganeti/' + version + '/api/hs/index.html'
29+
elif role == 'papi':
30+
ref = 'docs/ganeti/' + version + '/api/py/index.html'
31+
elif role == 'man':
32+
ref = 'docs/ganeti/' + version + '/man/index.html'
33+
elif role == 'api':
34+
ref = 'docs/ganeti/' + version + '/api/index.html'
35+
else:
36+
ref = 'nonexistent'
37+
set_classes(options)
38+
node = nodes.reference(rawtext, linktext, refuri=ref,
39+
**options)
40+
return [node], []
41+
42+
def setup(app):
43+
"""Sphinx extension callback.
44+
45+
"""
46+
app.add_role("gdoc", _GenericRole)
47+
app.add_role("hapi", _GenericRole)
48+
app.add_role("papi", _GenericRole)
49+
app.add_role("man", _GenericRole)
50+
app.add_role("api", _GenericRole)

‎gen_index.sh

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#!/bin/bash
2+
PYTHONPATH=docs.ganeti.org sphinx-build -b html -W docs.ganeti.org/ ./
3+
4+
# github pages has no directory index, create one here
5+
for v in docs/ganeti/*; do
6+
if [[ -d "${v}/man/" ]]; then
7+
tree -H '.' -L 1 --noreport --charset utf-8 -T "Ganeti ${v##docs/ganeti/} Manpages" -I index.html -o ${v}/man/index.html -- ${v}/man/
8+
fi
9+
done

0 commit comments

Comments
 (0)