Add DirectoryHTMLBuilder (contributed as PrettyHTMLBuilder by Will Maier).

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

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.
 

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 <target>' where <target> 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

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

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'),

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

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 <target>' where <target> 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 ^<target^>` where ^<target^> 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.