Initial commit of restbuilder.

Author: macfreek

CHANGES.rst

@@ -0,0 +1,15 @@
+Changelog
+=========
+
+restbuilder 0.1 (25 August 2013)
+--------------------------------
+* Code submitted to sphinx-contrib
+  https://bitbucket.org/birkenfeld/sphinx-contrib
+* Released as sphinxcontrib-restbuilder
+* Added basic documentation
+* Unsupported/unknown tags are not printed, but send to log facility.
+
+restbuilder (no version) (28 April 2012)
+-----------------------------------------
+* First release as port of a documentation generator in the NBT package
+  https://github.com/twoolie/NBT/commit/eefbd26c422a0e5f3c89e84fabcfb951a11722b0

LICENSE.txt

@@ -0,0 +1,25 @@
+Copyright (c) 2012-2013 by Freek Dijkstra <[email protected]>.
+Some rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -0,0 +1,3 @@
+include README.rst
+include LICENSE.txt
+include CHANGES.rst

README.rst

@@ -0,0 +1,93 @@
+.. -*- restructuredtext -*-
+
+=======================
+README for reST Builder
+=======================
+
+Sphinx_ extension to build reST (reStructuredText_) files.
+
+This extension is in particular useful to use in combination with the autodoc
+extension to automatically generate documentation for use by any rst parser
+(such as the GitHub wiki).
+
+In itself, the extension is fairly straightforward -- it takes the parsed reST 
+file from Sphinx_ and outputs it as reST.
+
+Requirements
+============
+
+* Sphinx_ 1.0 or later
+* Python 2.6 or later
+
+Installing
+==========
+
+Using pip
+---------
+
+    pip install sphinxcontrib-restbuilder
+
+Manual
+------
+
+    hg clone http://bitbucket.org/birkenfeld/sphinx-contrib
+    cd sphinx-contrib/restbuilder
+    python setup.py install
+
+If you want to take a look and have a try, you can put the reST builder in
+an extension subdirectory, and adjust ``sys.path`` to tell Sphinx where to
+look for it:
+
+- Add the extensions directory to the path in ``conf.py``. E.g.
+
+    sys.path.append(os.path.abspath('exts'))
+
+Usage
+=====
+
+- Set the builder as a extension in ``conf.py``:
+
+    extensions = ['sphinxcontrib.restbuilder']
+
+- Run sphinx-build with target ``rst``:
+
+    sphinx-build -b rst -c . build/rst
+
+Configuration
+=============
+
+The following four configuration variables are defined by sphinxcontrib.restbuilder:
+
+.. confval:: rst_file_suffix
+
+   This is the file name suffix for generated reST files.  The default is
+   ``".rst"``.
+
+.. confval:: rst_link_suffix
+
+   Suffix for generated links to reST files.  The default is whatever
+   :confval:`rst_file_suffix` is set to.
+
+.. confval:: rst_file_transform
+
+   Function to translate a docname to a filename. 
+   By default, returns `docname` + :confval:`rst_file_suffix`.
+
+.. confval:: rst_link_transform
+
+   Function to translate a docname to a (partial) URI. 
+   By default, returns `docname` + :confval:`rst_link_suffix`.
+
+
+Further Reading
+===============
+
+.. _Sphinx: http://sphinx-doc.org/
+.. _`sphinx-contrib`: http://bitbucket.org/birkenfeld/sphinx-contrib
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+Feedback
+========
+
+The reST builder is in a preliminary state. It's not (yet) widely used, so
+any feedback is particularly welcome.

setup.cfg

@@ -0,0 +1,6 @@
+[egg_info]
+tag_build = dev
+tag_date = true
+
+[aliases]
+release = egg_info -RDb ''

setup.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+
+from setuptools import setup, find_packages
+
+long_desc = '''
+Sphinx_ extension to build reST (reStructuredText_) files.
+
+This extension is in particular useful to use in combination with the autodoc
+extension to automatically generate documentation for use by any rst parser
+(such as the GitHub wiki).
+
+In itself, the extension is fairly straightforward -- it takes the parsed reST 
+file from Sphinx_ and outputs it as reST.
+
+.. _Sphinx: http://sphinx-doc.org/
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+'''
+
+requires = ['Sphinx>=1.0']
+
+setup(
+    name='sphinxcontrib-restbuilder',
+    version='0.1',
+    url='http://bitbucket.org/birkenfeld/sphinx-contrib',
+    download_url='http://pypi.python.org/pypi/sphinxcontrib-restbuilder',
+    license='BSD', # 2-clause
+    author='Freek Dijkstra',
+    author_email='[email protected]',
+    description='Sphinx extension to output reST files.',
+    long_description=long_desc,
+    zip_safe=False,
+    classifiers=[
+        'Development Status :: 4 - Beta',
+        'Environment :: Console',
+        'Environment :: Web Environment',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: BSD License',
+        'Operating System :: OS Independent',
+        'Programming Language :: Python',
+        'Topic :: Documentation',
+        'Topic :: Utilities',
+    ],
+    platforms='any',
+    packages=find_packages(),
+    include_package_data=True,
+    install_requires=requires,
+    namespace_packages=['sphinxcontrib'],
+)

sphinxcontrib/__init__.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinxcontrib
+    ~~~~~~~~~~~~~
+
+    This package is a namespace package that contains all extensions
+    distributed in the ``sphinx-contrib`` distribution.
+
+    :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+__import__('pkg_resources').declare_namespace(__name__)
+

sphinxcontrib/builders/__init__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinxcontrib.builders
+    ~~~~~~~~~~~~~~~~~~~~~~
+
+    Custom docutils builders.
+"""

sphinxcontrib/builders/rst.py

@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinxcontrib.builders.rst
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    ReST Sphinx builder.
+
+    :copyright: Copyright 2012-2013 by Freek Dijkstra.
+    :license: BSD, see LICENSE.txt for details.
+"""
+
+from __future__ import (print_function, unicode_literals, absolute_import)
+
+import codecs
+from os import path
+
+from docutils.io import StringOutput
+
+from sphinx.builders import Builder
+from sphinx.util.osutil import ensuredir, os_path, SEP
+from ..writers.rst import RstWriter
+
+
+# Clone of relative_uri() sphinx.util.osutil, with bug-fixes
+# since the original code had a few errors.
+# This was fixed in Sphinx 1.2b.
+def relative_uri(base, to):
+    """Return a relative URL from ``base`` to ``to``."""
+    if to.startswith(SEP):
+        return to
+    b2 = base.split(SEP)
+    t2 = to.split(SEP)
+    # remove common segments (except the last segment)
+    for x, y in zip(b2[:-1], t2[:-1]):
+        if x != y:
+            break
+        b2.pop(0)
+        t2.pop(0)
+    if b2 == t2:
+        # Special case: relative_uri('f/index.html','f/index.html')
+        # returns '', not 'index.html'
+        return ''
+    if len(b2) == 1 and t2 == ['']:
+        # Special case: relative_uri('f/index.html','f/') should 
+        # return './', not ''
+        return '.' +  SEP
+    return ('..' + SEP) * (len(b2)-1) + SEP.join(t2)
+
+
+class RstBuilder(Builder):
+    name = 'rst'
+    format = 'rst'
+    file_suffix = '.rst'
+    link_suffix = None  # defaults to file_suffix
+
+    def init(self):
+        """Load necessary templates and perform initialization."""
+        if self.config.rst_file_suffix is not None:
+            self.file_suffix = self.config.rst_file_suffix
+        if self.config.rst_link_suffix is not None:
+            self.link_suffix = self.config.rst_link_suffix
+        elif self.link_suffix == None:
+            self.link_suffix = self.file_suffix
+
+        # Function to convert the docname to a reST file name.
+        def file_transform(docname):
+            return docname + self.file_suffix
+        # Function to convert the docname to a relative URI.
+        def link_transform(docname):
+            return docname + self.link_suffix
+
+        if self.config.rst_file_transform != None:
+            self.file_transform = self.config.rst_file_transform
+        else:
+            self.file_transform = file_transform
+        if self.config.rst_link_transform != None:
+            self.link_transform = self.config.rst_link_transform
+        else:
+            self.link_transform = link_transform
+
+    def get_outdated_docs(self):
+        """
+        Return an iterable of input files that are outdated.
+        """
+        # This method is taken from TextBuilder.get_outdated_docs()
+        # with minor changes to support :confval:`rst_file_transform`.
+        for docname in self.env.found_docs:
+            if docname not in self.env.all_docs:
+                yield docname
+                continue
+            sourcename = path.join(self.env.srcdir, docname + 
+                        self.env.source_suffix)
+            targetname = path.join(self.outdir, self.file_transform(docname))
+            print (sourcename, targetname)
+
+            try:
+                targetmtime = path.getmtime(targetname)
+            except Exception:
+                targetmtime = 0
+            try:
+                srcmtime = path.getmtime(sourcename)
+                if srcmtime > targetmtime:
+                    yield docname
+            except EnvironmentError:
+                # source doesn't exist anymore
+                pass
+
+    def get_target_uri(self, docname, typ=None):
+        return self.link_transform(docname)
+
+    def get_relative_uri(self, from_, to, typ=None):
+        """
+        Return a relative URI between two source filenames.
+        """
+        # This is slightly different from Builder.get_relative_uri, 
+        # as it contains a small bug (which was fixed in Sphinx 1.2).
+        return relative_uri(self.get_target_uri(from_),
+                            self.get_target_uri(to, typ))
+
+    def prepare_writing(self, docnames):
+        self.writer = RstWriter(self)
+
+    def write_doc(self, docname, doctree):
+        # This method is taken from TextBuilder.write_doc()
+        # with minor changes to support :confval:`rst_file_transform`.
+        destination = StringOutput(encoding='utf-8')
+        # print "write(%s,%s)" % (type(doctree), type(destination))
+
+        self.writer.write(doctree, destination)
+        outfilename = path.join(self.outdir, self.file_transform(docname))
+        # print "write(%s,%s) -> %s" % (type(doctree), type(destination), outfilename)
+        ensuredir(path.dirname(outfilename))
+        try:
+            f = codecs.open(outfilename, 'w', 'utf-8')
+            try:
+                f.write(self.writer.output)
+            finally:
+                f.close()
+        except (IOError, OSError), err:
+            self.warn("error writing file %s: %s" % (outfilename, err))
+
+    def finish(self):
+        pass

sphinxcontrib/restbuilder.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinxcontrib.restbuilder
+    =========================
+
+    Sphinx extension to output reST files.
+
+    .. moduleauthor:: Freek Dijkstra <[email protected]>
+
+    :copyright: Copyright 2012-2013 by Freek Dijkstra.
+    :license: BSD, see LICENSE.txt for details.
+"""
+
+from __future__ import (print_function, unicode_literals, absolute_import)
+
+from sphinx.builders import Builder
+from .builders.rst import RstBuilder
+from .writers.rst import RstWriter
+
+
+
+def setup(app):
+    app.require_sphinx('1.0')
+    app.add_builder(RstBuilder)
+    app.add_config_value('rst_file_suffix', ".rst", False)
+    """This is the file name suffix for reST files"""
+    app.add_config_value('rst_link_suffix', None, False)
+    """The is the suffix used in internal links. By default, takes the same value as rst_file_suffix"""
+    app.add_config_value('rst_file_transform', None, False)
+    """Function to translate a docname to a filename. By default, returns docname + rst_file_suffix."""
+    app.add_config_value('rst_link_transform', None, False)
+    """Function to translate a docname to a (partial) URI. By default, returns docname + rst_link_suffix."""