diff --git a/docs/contribute.rst b/docs/contribute.rst index 2f5ef873..a96f2d02 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -105,13 +105,15 @@ environments. Building the docs ----------------- -If you make changes to the documentation, you should preview your changes -before committing them:: +If you make changes to the documentation, you should build and inspect your +changes before committing them:: - cd docs - make html + invoke docserve -Open ``_build/html/index.html`` in your browser to preview the documentation. +Open http://localhost:8000 in your browser to review the documentation. While +the above task is running, any changes you make and save to the documentation +should automatically appear in the browser, as it live-reloads when it detects +changes to the documentation source files. Plugin development ------------------ diff --git a/pyproject.toml b/pyproject.toml index a7afc595..8b9db0c6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -48,6 +48,7 @@ markdown = "~3.1.1" typogrify = "^2.0" sphinx = "=1.4.9" sphinx_rtd_theme = "^0.4.3" +livereload = "^2.6" mock = "^3.0" pytest = "^5.2" pytest-cov = "^2.8" diff --git a/requirements/docs.pip b/requirements/docs.pip index 525bdc40..acc5d5f5 100644 --- a/requirements/docs.pip +++ b/requirements/docs.pip @@ -1,2 +1,3 @@ sphinx==1.4.9 sphinx_rtd_theme +livereload diff --git a/tasks.py b/tasks.py index 8ecfc467..42642e6a 100644 --- a/tasks.py +++ b/tasks.py @@ -6,6 +6,7 @@ from invoke import task PKG_NAME = "pelican" PKG_PATH = Path("pelican") +DOCS_PORT = os.environ.get("DOCS_PORT", 8000) ACTIVE_VENV = os.environ.get("VIRTUAL_ENV", None) VENV_HOME = Path(os.environ.get("WORKON_HOME", "~/virtualenvs")) VENV_PATH = Path(ACTIVE_VENV) if ACTIVE_VENV else (VENV_HOME / PKG_NAME) @@ -18,6 +19,24 @@ PRECOMMIT = ( ) +@task +def docbuild(c): + """Build documentation""" + c.run(f"{VENV}/bin/sphinx-build docs docs/_build") + + +@task(docbuild) +def docserve(c): + """Serve docs at http://localhost:$DOCS_PORT/ (default port is 8000)""" + from livereload import Server + + server = Server() + server.watch("docs/conf.py", lambda: docbuild(c)) + server.watch("CONTRIBUTING.rst", lambda: docbuild(c)) + server.watch("docs/*.rst", lambda: docbuild(c)) + server.serve(port=DOCS_PORT, root="docs/_build") + + @task def tests(c): """Run the test suite"""