diff --git a/doc/development/tutorials/builders.rst b/doc/development/builders.rst similarity index 79% rename from doc/development/tutorials/builders.rst rename to doc/development/builders.rst index b2e43a2ae..bb6777023 100644 --- a/doc/development/tutorials/builders.rst +++ b/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. diff --git a/doc/development/index.rst b/doc/development/index.rst index 6a3406a20..2025b3ec7 100644 --- a/doc/development/index.rst +++ b/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 diff --git a/doc/development/tutorials/theming-dev.rst b/doc/development/theming.rst similarity index 95% rename from doc/development/tutorials/theming-dev.rst rename to doc/development/theming.rst index ad6b73a6c..ea993e679 100644 --- a/doc/development/tutorials/theming-dev.rst +++ b/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: -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 diff --git a/doc/development/tutorials/index.rst b/doc/development/tutorials/index.rst index 9acfc6c76..3b625090d 100644 --- a/doc/development/tutorials/index.rst +++ b/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 diff --git a/doc/development/tutorials/overview.rst b/doc/development/tutorials/overview.rst index 8ffb8df42..ad474999a 100644 --- a/doc/development/tutorials/overview.rst +++ b/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 diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst index 0c088e8c9..e5362b9f0 100644 --- a/doc/usage/theming.rst +++ b/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: