{"id":13571520,"url":"https://github.com/sphinx-doc/sphinx-autobuild","last_synced_at":"2026-03-16T16:39:55.761Z","repository":{"id":12764774,"uuid":"15438125","full_name":"sphinx-doc/sphinx-autobuild","owner":"sphinx-doc","description":"Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a hot-reload web server.","archived":false,"fork":false,"pushed_at":"2024-10-02T23:15:07.000Z","size":536,"stargazers_count":567,"open_issues_count":23,"forks_count":82,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-04-13T18:44:40.784Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sphinx-doc.png","metadata":{"files":{"readme":"README.rst","changelog":"NEWS.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE.rst","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-12-25T17:09:56.000Z","updated_at":"2025-04-12T14:42:57.000Z","dependencies_parsed_at":"2023-01-13T17:07:40.070Z","dependency_job_id":"13b9bf61-d27d-4679-b5b5-c5bfd0fb2383","html_url":"https://github.com/sphinx-doc/sphinx-autobuild","commit_stats":{"total_commits":301,"total_committers":29,"mean_commits":"10.379310344827585","dds":0.7308970099667774,"last_synced_commit":"7a8fa1206c65bbd993af7345cf7e9d0f8013d8ed"},"previous_names":["garetjax/sphinx-autobuild","executablebooks/sphinx-autobuild"],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-doc%2Fsphinx-autobuild","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-doc%2Fsphinx-autobuild/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-doc%2Fsphinx-autobuild/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-doc%2Fsphinx-autobuild/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sphinx-doc","download_url":"https://codeload.github.com/sphinx-doc/sphinx-autobuild/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254235701,"owners_count":22036964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T14:01:02.745Z","updated_at":"2026-03-16T16:39:55.749Z","avatar_url":"https://github.com/sphinx-doc.png","language":"Python","readme":"================\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 \u003chttps://pypi.org/project/sphinx-autobuild/\u003e`__.\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     --post-build COMMAND  additional command(s) to run after 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 \u003crelevant sphinx bugs_\u003e`__\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 \u0026\n   sphinx-autobuild --port=0 --open-browser magikarp/docs magickarp/docs/_build/html \u0026\n\nNotifications for build cycles\n------------------------------\n\nAs an example of using the ``--pre-build`` and ``--post-build`` arguments,\nthe command below uses `notify-send` to send a notification when a build\nstarts and finishes.\n\n.. code-block:: bash\n\n   sphinx-autobuild docs docs/_build/html/ \\\n      --pre-build 'notify-send \"sphinx-autobuild: build start\"' \\\n      --post-build 'notify-send \"sphinx-autobuild: build end\"'\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\nDebugging\n=========\n\nIf the ``SPHINX_AUTOBUILD_DEBUG`` environment variable is present,\nis not ``\"\"`` (the empty string) or ``0``,\nand a file change is detected,\nits path and the currently active ignore expressions are printed.\nThis is to help setting up the ignore expressions correctly.\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","funding_links":[],"categories":["Python","Documentation"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsphinx-doc%2Fsphinx-autobuild","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsphinx-doc%2Fsphinx-autobuild","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsphinx-doc%2Fsphinx-autobuild/lists"}