rearranging a few docs and small updates

doc/development/builders.rst

@@ -15,16 +15,18 @@ group. The name of the entry point needs to match your builder's
 :attr:`~.Builder.name` attribute, which is the name passed to the
 :option:`sphinx-build -b` option. The entry point value should equal the
 dotted name of the extension module. Here is an example of how an entry point
-for 'mybuilder' can be defined in the extension's ``setup.py``::
+for 'mybuilder' can be defined in the extension's ``setup.py``
 
-    setup(
-        # ...
-        entry_points={
-            'sphinx.builders': [
-                'mybuilder = my.extension.module',
-            ],
-        }
-    )
+.. code-block:: python
+
+   setup(
+       # ...
+       entry_points={
+           'sphinx.builders': [
+               'mybuilder = my.extension.module',
+           ],
+       }
+   )
 
 Note that it is still necessary to register the builder using
 :meth:`~.Sphinx.add_builder` in the extension's :func:`setup` function.

doc/development/index.rst

@@ -11,3 +11,10 @@ wish to use Sphinx with existing extensions, refer to :doc:`/usage/index`.
    :maxdepth: 2
 
    tutorials/index
+   builders
+
+.. toctree::
+   :caption: Theming
+   :maxdepth: 2
+
+   theming

doc/development/theming.rst

@@ -231,6 +231,7 @@ function as a callback for :event:`html-page-context`.
             return "Your string is %s" % mystring
         # Add it to the page's context
         context['my_func'] = my_func
+
     # Your extension's setup function
     def setup(app):
         app.connect("html-page-context", setup_my_func)
@@ -244,7 +245,7 @@ Now, you will have access to this function in jinja like so:
    </div>
 
 
-Inject javsacript based on user configuration
+Inject JavaScript based on user configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If your extension makes use of JavaScript, it can be useful to allow users
@@ -257,15 +258,34 @@ configuration.
 
 First, you may append ``_t`` to the end of any static files included with your
 extension. This will cause Sphinx to process these files with the templating
-engine, allowing you to embed variables and control behavior. See
-:ref:`theming-static-templates` for more information.
+engine, allowing you to embed variables and control behavior.
+
+For example, the following JavaScript structure:
+
+.. code-block:: bash
+
+   mymodule/
+   ├── _static
+   │   └── myjsfile.js_t
+   └── mymodule.py
+
+Will result in the following static file placed in your HTML's build output:
+
+.. code-block:: bash
+
+   _build/
+   └── html
+       └── _static
+           └── myjsfile.js
+
+See :ref:`theming-static-templates` for more information.
 
 Second, you may use the :meth:`Sphinx.add_js_file` method without pointing it
 to a file. Normally, this method is used to insert a new JavaScript file
 into your site. However, if you do *not* pass a file path, but instead pass
 a string to the "body" argument, then this text will be inserted as JavaScript
 into your site's head. This allows you to insert variables into your project's
-javascript from Python.
+JavaScript from Python.
 
 For example, the following code will read in a user-configured value and then
 insert this value as a JavaScript variable, which your extension's JavaScript

doc/development/tutorials/index.rst

@@ -9,7 +9,6 @@ Refer to the following tutorials to get started with extension development.
    :caption: General extension tutorials
 
    overview
-   builders
 
 .. toctree::
    :caption: Directive tutorials
@@ -18,9 +17,3 @@ Refer to the following tutorials to get started with extension development.
    helloworld
    todo
    recipe
-
-.. toctree::
-   :caption: Theming
-   :maxdepth: 1
-
-   theming-dev

doc/development/tutorials/overview.rst

@@ -19,7 +19,7 @@ use the :meth:`Sphinx.setup_extension` method. This will
 activate another extension at run-time, ensuring that you have access to its
 functionality.
 
-For example, the following code activates the "recommonmark" extension:
+For example, the following code activates the ``recommonmark`` extension:
 
 .. code-block:: python
 

doc/usage/theming.rst

@@ -22,7 +22,7 @@ Themes
 
    This section provides information about using pre-existing HTML themes. If
    you wish to create your own theme, refer to
-   :doc:`/development/tutorials/theming-dev`.
+   :doc:`/development/theming`.
 
 Sphinx supports changing the appearance of its HTML output via *themes*.  A
 theme is a collection of HTML templates, stylesheet(s) and other static files.
@@ -81,7 +81,7 @@ zipfile-based theme::
     html_theme = "dotted"
 
 For more information on the design of themes, including information about
-writing your own themes, refer to :doc:`/development/tutorials/theming-dev`.
+writing your own themes, refer to :doc:`/development/theming`.
 
 .. _builtin-themes: