Add Invoke tasks for building and serving docs

docs/contribute.rst

@@ -105,13 +105,15 @@ environments.
 Building the docs
 -----------------
 
-If you make changes to the documentation, you should preview your changes
+If you make changes to the documentation, you should build and inspect your
-before committing them::
+changes before committing them::
 
-    cd docs
+    invoke docserve
-    make html
 
-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
 ------------------

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"

requirements/docs.pip

@@ -1,2 +1,3 @@
 sphinx==1.4.9
 sphinx_rtd_theme
+livereload

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"""