From 2dff2e3bfa291ed7dfdd75dae35b2932a0f89560 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 00:07:47 +0100 Subject: [PATCH] Add DirectoryHTMLBuilder (contributed as PrettyHTMLBuilder by Will Maier). --- AUTHORS | 1 + CHANGES | 7 ++++++- doc/Makefile | 9 ++++++++- doc/builders.rst | 13 +++++++++++++ sphinx/builders/__init__.py | 1 + sphinx/builders/html.py | 34 +++++++++++++++++++++++++++++++--- sphinx/quickstart.py | 17 ++++++++++++++++- 7 files changed, 76 insertions(+), 6 deletions(-) diff --git a/AUTHORS b/AUTHORS index c13d267e2..0d8afda5a 100644 --- a/AUTHORS +++ b/AUTHORS @@ -11,6 +11,7 @@ Other contributors, listed alphabetically, are: * Martin Hans -- autodoc improvements * Dave Kuhlman -- original LaTeX writer * Thomas Lamb -- linkcheck builder +* Will Maier -- directory HTML builder * Benjamin Peterson -- unittests * Stefan Seefeld -- toctree improvements * Antonio Valentino -- qthelp builder diff --git a/CHANGES b/CHANGES index 510738b4a..8170cb94b 100644 --- a/CHANGES +++ b/CHANGES @@ -25,7 +25,7 @@ New features added if name.startswith('_'): return True -* Theming support. +* Theming support, see the new section in the documentation. * Markup: @@ -98,6 +98,11 @@ New features added - New builder for Qt help collections, by Antonio Valentino. + - The new ``DirectoryHTMLBuilder`` (short name ``dirhtml``) creates + a separate directory for every page, and places the page there + in a file called ``index.html``. Therefore, page URLs and links + don't need to contain ``.html``. + - The new ``html_link_suffix`` config value can be used to select the suffix of generated links between HTML files. diff --git a/doc/Makefile b/doc/Makefile index 6da1654bb..07cee7449 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -11,11 +11,12 @@ PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \ $(SPHINXOPTS) . -.PHONY: help clean html pickle htmlhelp qthelp latex changes linkcheck doctest +.PHONY: help clean html dirhtml pickle htmlhelp qthelp latex changes linkcheck doctest help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files called index.html in directories" @echo " pickle to make pickle files" @echo " htmlhelp to make HTML files and a HTML help project" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @@ -31,6 +32,12 @@ html: @echo @echo "Build finished. The HTML pages are in _build/html." +dirhtml: + mkdir -p _build/dirhtml _build/doctrees + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml + @echo + @echo "Build finished. The HTML pages are in _build/dirhtml." + text: mkdir -p _build/text _build/doctrees $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text diff --git a/doc/builders.rst b/doc/builders.rst index 0055a28b6..bee0094c6 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -23,6 +23,19 @@ The builder's "name" must be given to the **-b** command-line option of Its name is ``html``. +.. class:: DirectoryHTMLBuilder + + This is a subclass of the standard HTML builder. Its output is a directory + with HTML files, where each file is called ``index.html`` and placed in a + subdirectory named like its page name. For example, the document + ``markup/rest.rst`` will not result in an output file ``markup/rest.html``, + but ``markup/rest/index.html``. When generating links between pages, the + ``index.html`` is omitted, so that the URL would look like ``markup/rest/``. + + Its name is ``dirhtml``. + + .. versionadded:: 0.6 + .. class:: HTMLHelpBuilder This builder produces the same output as the standalone HTML builder, but diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 46054460d..19699033f 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -352,6 +352,7 @@ class Builder(object): BUILTIN_BUILDERS = { 'html': ('html', 'StandaloneHTMLBuilder'), + 'dirhtml': ('html', 'DirectoryHTMLBuilder'), 'pickle': ('html', 'PickleHTMLBuilder'), 'json': ('html', 'JSONHTMLBuilder'), 'web': ('html', 'PickleHTMLBuilder'), diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 61c0c0b14..93f5181c0 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -560,6 +560,9 @@ class StandaloneHTMLBuilder(Builder): return self.render_partial(self.env.get_toctree_for( docname, self, collapse))['fragment'] + def get_outfilename(self, pagename): + return path.join(self.outdir, os_path(pagename) + self.out_suffix) + # --------- these are overwritten by the serialization builder def get_target_uri(self, docname, typ=None): @@ -587,8 +590,7 @@ class StandaloneHTMLBuilder(Builder): output = self.templates.render(templatename, ctx) if not outfilename: - outfilename = path.join(self.outdir, - os_path(pagename) + self.out_suffix) + outfilename = self.get_outfilename(pagename) # outfilename's path is in general different from self.outdir ensuredir(path.dirname(outfilename)) try: @@ -636,9 +638,35 @@ class StandaloneHTMLBuilder(Builder): self.info('done') +class DirectoryHTMLBuilder(StandaloneHTMLBuilder): + """ + A StandaloneHTMLBuilder that creates all HTML pages as "index.html" in + a directory given by their pagename, so that generated URLs don't have + ``.html`` in them. + """ + name = 'dirhtml' + + def get_target_uri(self, docname, typ=None): + if docname == 'index': + return '' + if docname.endswith(SEP + 'index'): + return docname[:-5] # up to sep + return docname + SEP + + def get_outfilename(self, pagename): + if pagename == 'index' or pagename.endswith(SEP + 'index'): + outfilename = path.join(self.outdir, os_path(pagename) + + self.out_suffix) + else: + outfilename = path.join(self.outdir, os_path(pagename), + 'index' + self.out_suffix) + + return outfilename + + class SerializingHTMLBuilder(StandaloneHTMLBuilder): """ - An abstract builder that serializes the HTML generated. + An abstract builder that serializes the generated HTML. """ #: the serializing implementation to use. Set this to a module that #: implements a `dump`, `load`, `dumps` and `loads` functions diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index d2a1c62db..d3cf18c5f 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -263,11 +263,13 @@ PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d %(rbuilddir)s/doctrees $(PAPEROPT_$(PAPER)) \ $(SPHINXOPTS) %(rsrcdir)s -.PHONY: help clean html pickle json htmlhelp qthelp latex changes linkcheck doctest +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes \ +linkcheck doctest help: \t@echo "Please use \\`make ' where is one of" \t@echo " html to make standalone HTML files" +\t@echo " dirhtml to make HTML files named index.html in directories" \t@echo " pickle to make pickle files" \t@echo " json to make JSON files" \t@echo " htmlhelp to make HTML files and a HTML help project" @@ -285,6 +287,11 @@ html: \t@echo \t@echo "Build finished. The HTML pages are in %(rbuilddir)s/html." +dirhtml: +\t$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) %(rbuilddir)s/dirhtml +\t@echo +\t@echo "Build finished. The HTML pages are in %(rbuilddir)s/dirhtml." + pickle: \t$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) %(rbuilddir)s/pickle \t@echo @@ -351,6 +358,7 @@ if "%%1" == "help" ( \t:help \techo.Please use `make ^` where ^ is one of \techo. html to make standalone HTML files +\techo. dirhtml to make HTML files named index.html in directories \techo. pickle to make pickle files \techo. json to make JSON files \techo. htmlhelp to make HTML files and a HTML help project @@ -375,6 +383,13 @@ if "%%1" == "html" ( \tgoto end ) +if "%%1" == "dirhtml" ( +\t%%SPHINXBUILD%% -b dirhtml %%ALLSPHINXOPTS%% %(rbuilddir)s/dirhtml +\techo. +\techo.Build finished. The HTML pages are in %(rbuilddir)s/dirhtml. +\tgoto end +) + if "%%1" == "pickle" ( \t%%SPHINXBUILD%% -b pickle %%ALLSPHINXOPTS%% %(rbuilddir)s/pickle \techo.