diff --git a/docs/contributing.rst b/docs/contributing.rst index 993d01d8..27e3b0db 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -91,7 +91,7 @@ You can build it locally by installing ``sphinx`` and ``sphinx_rtd_theme`` in yo source venv/bin/activate # Install the dependencies needed to build the docs - pip install sphinx sphinx_rtd_theme + pip install -e .[docs] # Now build the docs cd docs/ @@ -103,16 +103,14 @@ This will create the HTML version of the documentation in ``docs/_build/html``. Any time you make changes to a ``.rst`` file you can re-run ``make html`` to update the built documents, then refresh them in your browser. -For added productivity, you can run Sphinx in auto-build mode. This will run a local webserver serving the docs that automatically rebuilds them and refreshes the page any time you hit save in your editor. +For added productivity, you can use use `sphinx-autobuild `__ to run Sphinx in auto-build mode. This will run a local webserver serving the docs that automatically rebuilds them and refreshes the page any time you hit save in your editor. -To enable auto-build mode, first install `sphinx-autobuild `__:: - - pip install sphinx-autobuild - -Now start the server by running:: +``sphinx-autobuild`` will have been installed when you ran ``pip install -e .[docs]``. In your ``docs/`` directory you can start the server by running the following:: make livehtml +Now browse to ``http://localhost:8000/`` to view the documentation. Any edits you make should be instantly relected in your browser. + .. _contributing_release: Release process diff --git a/setup.py b/setup.py index edb8d51e..fdbb948e 100644 --- a/setup.py +++ b/setup.py @@ -56,10 +56,7 @@ setup( """, setup_requires=["pytest-runner"], extras_require={ - "docs": [ - "sphinx_rtd_theme", - "sphinx-autobuild", - ], + "docs": ["sphinx_rtd_theme", "sphinx-autobuild"], "test": [ "pytest==4.6.1", "pytest-asyncio==0.10.0", @@ -67,7 +64,7 @@ setup( "beautifulsoup4==4.6.1", "asgiref==3.1.2", ] - + maybe_black + + maybe_black, }, tests_require=["datasette[test]"], classifiers=[