| Name | sphinx-autobuild JSON |
| Version |
2024.4.13
JSON |
| download |
| home_page | None |
| Summary | Rebuild Sphinx documentation on changes, with hot reloading in the browser. |
| upload_time | 2024-04-13 01:31:31 |
| maintainer | None |
| docs_url | None |
| author | Adam Turner |
| requires_python | >=3.9 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
================
sphinx-autobuild
================
.. image:: https://img.shields.io/pypi/v/sphinx-autobuild.svg
:target: https://pypi.org/project/sphinx-autobuild/
:alt: Package on PyPI
.. image:: https://img.shields.io/badge/License-MIT-blue.svg
:target: https://opensource.org/licenses/MIT
:alt: MIT
Rebuild Sphinx documentation on changes, with hot reloading in the browser.
.. image:: ./docs/_static/demo.png
:align: center
:alt: preview screenshot
Installation
============
sphinx-autobuild is available on `PyPI <https://pypi.org/project/sphinx-autobuild/>`__.
It can be installed using pip:
.. code-block:: bash
pip install sphinx-autobuild
Usage
=====
To build a classical Sphinx documentation set, run:
.. code-block:: bash
sphinx-autobuild docs docs/_build/html
This will start a server at http://127.0.0.1:8000
and start watching for changes in the ``docs/`` directory.
When a change is detected in ``docs/``, the documentation is rebuilt
and any open browser windows are reloaded automatically.
``KeyboardInterrupt`` (``ctrl`` + ``c``) will stop the server.
Command line options
====================
sphinx-autobuild accepts the same arguments as ``sphinx-build``
(these get passed to sphinx-build on each build).
It also has a few additional options,
which can seen by running ``sphinx-autobuild --help``:
.. code-block:: console
$ sphinx-autobuild --help
usage: sphinx-autobuild [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
...
autobuild options:
--port PORT port to serve documentation on. 0 means find and use a free port
--host HOST hostname to serve documentation on
--re-ignore RE_IGNORE
regular expression for files to ignore, when watching for changes
--ignore IGNORE glob expression for files to ignore, when watching for changes
--no-initial skip the initial build
--open-browser open the browser after building documentation
--delay DELAY how long to wait before opening the browser
--watch DIR additional directories to watch
--pre-build COMMAND additional command(s) to run prior to building the documentation
Using with Makefile
-------------------
FYI: Sphinx is planning to `move away from`_ using `Makefile`.
To use sphinx-autobuild with the Makefile generated by Sphinx,
add the following to the end of the Makefile:
.. code-block:: make
livehtml:
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
``make livehtml`` will now invoke sphinx-autobuild.
If you generated the `Makefile` with an older version of sphinx,
this syntax might not work for you.
Consider `updating to the newer structure`_.
.. _move away from: https://github.com/sphinx-doc/sphinx/issues/5618#issuecomment-502415633
.. _updating to the newer structure: https://github.com/sphinx-doc/sphinx/blob/v3.0.0/sphinx/templates/quickstart/Makefile.new_t
Automatically opening the browser
---------------------------------
sphinx-autobuild can open the homepage of the generated documentation
in your default browser.
Passing ``--open-browser`` will enable this behaviour.
Automatically selecting a port
------------------------------
sphinx-autobuild asks the operating system for a free port number
and use that for its server.
Passing ``--port=0`` will enable this behaviour.
Workflow suggestions
====================
Working on a Sphinx HTML theme
------------------------------
When working on a Sphinx HTML theme,
add the source directory of the theme as a watch directory.
It is also recommended to disable Sphinx's incremental builds
by passing the ``-a`` option to sphinx-autobuild.
.. code-block:: bash
sphinx-autobuild -a docs docs/_build/html --watch path/to/theme
This results in slower builds, but it ensures that
all pages are built from the same state of the HTML theme.
It also works around a `known issue in Sphinx <relevant sphinx bugs_>`__
which causes significant problems during theme development.
Working on multiple projects
----------------------------
When working on multiple Sphinx documentation projects simultaneously,
it is required to use different output directories for each project.
It is also recommended to use ``--port=0`` and ``--open-browser``
to avoid needing to manually manage ports and opening browser windows
(which can get tedious quickly).
.. code-block:: bash
sphinx-autobuild --port=0 --open-browser pikachu/docs pikachu/docs/_build/html &
sphinx-autobuild --port=0 --open-browser magikarp/docs magickarp/docs/_build/html &
Relevant Sphinx Bugs
====================
Sphinx does not `detect changes in non-document, non-code files in incremental mode`__,
like theme files and static files.
At the time of writing, the only known workaround is
to instruct Sphinx to rebuild the relevant pages.
This can be done by disabling incremental mode (with ``-a``)
or passing relevant ``filenames`` in addition to source and output directory in the CLI.
__ https://github.com/sphinx-doc/sphinx-autobuild/issues/34
Acknowledgements
================
This project stands on the shoulders of giants,
without whom this project would not be possible.
Many thanks to everyone who has `contributed code`_ as well as
participated in `discussions on the issue tracker`_.
This project is better thanks to your contribution.
.. _contributed code: https://github.com/sphinx-doc/sphinx-autobuild/graphs/contributors
.. _discussions on the issue tracker: https://github.com/sphinx-doc/sphinx-autobuild/issues
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-autobuild",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Adam Turner",
"author_email": "Jonathan Stoppani <jonathan@stoppani.name>",
"download_url": "https://files.pythonhosted.org/packages/a1/4e/77c2f38f3fa862583e1f86fa4e9020f7c9f32199b06de46d7e3e09e3107f/sphinx_autobuild-2024.4.13.tar.gz",
"platform": null,
"description": "================\nsphinx-autobuild\n================\n\n.. image:: https://img.shields.io/pypi/v/sphinx-autobuild.svg\n :target: https://pypi.org/project/sphinx-autobuild/\n :alt: Package on PyPI\n\n.. image:: https://img.shields.io/badge/License-MIT-blue.svg\n :target: https://opensource.org/licenses/MIT\n :alt: MIT\n\nRebuild Sphinx documentation on changes, with hot reloading in the browser.\n\n.. image:: ./docs/_static/demo.png\n :align: center\n :alt: preview screenshot\n\nInstallation\n============\n\nsphinx-autobuild is available on `PyPI <https://pypi.org/project/sphinx-autobuild/>`__.\nIt can be installed using pip:\n\n.. code-block:: bash\n\n pip install sphinx-autobuild\n\nUsage\n=====\n\nTo build a classical Sphinx documentation set, run:\n\n.. code-block:: bash\n\n sphinx-autobuild docs docs/_build/html\n\nThis will start a server at http://127.0.0.1:8000\nand start watching for changes in the ``docs/`` directory.\nWhen a change is detected in ``docs/``, the documentation is rebuilt\nand any open browser windows are reloaded automatically.\n``KeyboardInterrupt`` (``ctrl`` + ``c``) will stop the server.\n\nCommand line options\n====================\n\nsphinx-autobuild accepts the same arguments as ``sphinx-build``\n(these get passed to sphinx-build on each build).\nIt also has a few additional options,\nwhich can seen by running ``sphinx-autobuild --help``:\n\n.. code-block:: console\n\n $ sphinx-autobuild --help\n usage: sphinx-autobuild [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]\n\n ...\n\n autobuild options:\n --port PORT port to serve documentation on. 0 means find and use a free port\n --host HOST hostname to serve documentation on\n --re-ignore RE_IGNORE\n regular expression for files to ignore, when watching for changes\n --ignore IGNORE glob expression for files to ignore, when watching for changes\n --no-initial skip the initial build\n --open-browser open the browser after building documentation\n --delay DELAY how long to wait before opening the browser\n --watch DIR additional directories to watch\n --pre-build COMMAND additional command(s) to run prior to building the documentation\n\nUsing with Makefile\n-------------------\n\n FYI: Sphinx is planning to `move away from`_ using `Makefile`.\n\nTo use sphinx-autobuild with the Makefile generated by Sphinx,\nadd the following to the end of the Makefile:\n\n.. code-block:: make\n\n livehtml:\n sphinx-autobuild \"$(SOURCEDIR)\" \"$(BUILDDIR)\" $(SPHINXOPTS) $(O)\n\n``make livehtml`` will now invoke sphinx-autobuild.\n\n If you generated the `Makefile` with an older version of sphinx,\n this syntax might not work for you.\n Consider `updating to the newer structure`_.\n\n.. _move away from: https://github.com/sphinx-doc/sphinx/issues/5618#issuecomment-502415633\n.. _updating to the newer structure: https://github.com/sphinx-doc/sphinx/blob/v3.0.0/sphinx/templates/quickstart/Makefile.new_t\n\nAutomatically opening the browser\n---------------------------------\n\nsphinx-autobuild can open the homepage of the generated documentation\nin your default browser.\nPassing ``--open-browser`` will enable this behaviour.\n\nAutomatically selecting a port\n------------------------------\n\nsphinx-autobuild asks the operating system for a free port number\nand use that for its server.\nPassing ``--port=0`` will enable this behaviour.\n\n\nWorkflow suggestions\n====================\n\nWorking on a Sphinx HTML theme\n------------------------------\n\nWhen working on a Sphinx HTML theme,\nadd the source directory of the theme as a watch directory.\nIt is also recommended to disable Sphinx's incremental builds\nby passing the ``-a`` option to sphinx-autobuild.\n\n.. code-block:: bash\n\n sphinx-autobuild -a docs docs/_build/html --watch path/to/theme\n\n\nThis results in slower builds, but it ensures that\nall pages are built from the same state of the HTML theme.\nIt also works around a `known issue in Sphinx <relevant sphinx bugs_>`__\nwhich causes significant problems during theme development.\n\nWorking on multiple projects\n----------------------------\n\nWhen working on multiple Sphinx documentation projects simultaneously,\nit is required to use different output directories for each project.\nIt is also recommended to use ``--port=0`` and ``--open-browser``\nto avoid needing to manually manage ports and opening browser windows\n(which can get tedious quickly).\n\n.. code-block:: bash\n\n sphinx-autobuild --port=0 --open-browser pikachu/docs pikachu/docs/_build/html &\n sphinx-autobuild --port=0 --open-browser magikarp/docs magickarp/docs/_build/html &\n\nRelevant Sphinx Bugs\n====================\n\nSphinx does not `detect changes in non-document, non-code files in incremental mode`__,\nlike theme files and static files.\n\nAt the time of writing, the only known workaround is\nto instruct Sphinx to rebuild the relevant pages.\nThis can be done by disabling incremental mode (with ``-a``)\nor passing relevant ``filenames`` in addition to source and output directory in the CLI.\n\n__ https://github.com/sphinx-doc/sphinx-autobuild/issues/34\n\nAcknowledgements\n================\n\nThis project stands on the shoulders of giants,\nwithout whom this project would not be possible.\n\nMany thanks to everyone who has `contributed code`_ as well as\nparticipated in `discussions on the issue tracker`_.\nThis project is better thanks to your contribution.\n\n.. _contributed code: https://github.com/sphinx-doc/sphinx-autobuild/graphs/contributors\n.. _discussions on the issue tracker: https://github.com/sphinx-doc/sphinx-autobuild/issues\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Rebuild Sphinx documentation on changes, with hot reloading in the browser.",
"version": "2024.4.13",
"project_urls": {
"Changelog": "https://github.com/sphinx-doc/sphinx-autobuild/blob/main/NEWS.rst",
"Documentation": "https://github.com/sphinx-doc/sphinx-autobuild#readme",
"Download": "https://pypi.org/project/sphinx-autobuild/",
"Issue tracker": "https://github.com/sphinx-doc/sphinx-autobuild/issues",
"Source": "https://github.com/sphinx-doc/sphinx-autobuild"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2e50e329deef38c1224f300b117f0c1ee04de3bd5bb9ecbb416d83b177e243d0",
"md5": "108e876cc695ceb76a15fdbbbc00e259",
"sha256": "97fae5ab04515fef9c7d1aca977082ec60417861eff6406acb06cb95d41d7601"
},
"downloads": -1,
"filename": "sphinx_autobuild-2024.4.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "108e876cc695ceb76a15fdbbbc00e259",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11178,
"upload_time": "2024-04-13T01:31:29",
"upload_time_iso_8601": "2024-04-13T01:31:29.351227Z",
"url": "https://files.pythonhosted.org/packages/2e/50/e329deef38c1224f300b117f0c1ee04de3bd5bb9ecbb416d83b177e243d0/sphinx_autobuild-2024.4.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a14e77c2f38f3fa862583e1f86fa4e9020f7c9f32199b06de46d7e3e09e3107f",
"md5": "76b587e50f64c637a2bf0db7b657c3b7",
"sha256": "1d023b3a11866a094cd55c8e5a68c155430c033d560f649c1c2bde818f1d8f1b"
},
"downloads": -1,
"filename": "sphinx_autobuild-2024.4.13.tar.gz",
"has_sig": false,
"md5_digest": "76b587e50f64c637a2bf0db7b657c3b7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12959,
"upload_time": "2024-04-13T01:31:31",
"upload_time_iso_8601": "2024-04-13T01:31:31.050762Z",
"url": "https://files.pythonhosted.org/packages/a1/4e/77c2f38f3fa862583e1f86fa4e9020f7c9f32199b06de46d7e3e09e3107f/sphinx_autobuild-2024.4.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-13 01:31:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sphinx-doc",
"github_project": "sphinx-autobuild",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-autobuild"
}
