docs(dev): add meta docs on writing docs

docs/dev/development/documentation.rst

@@ -0,0 +1,126 @@
+#############
+Documentation
+#############
+
+Developer documentation
+=======================
+
+The developer documentation is hosted at `warehouse.pypa.io`_. It's written in
+`reStructuredText`_ or `Markdown`_ (via `MyST`_) and built using
+`Sphinx`_.
+
+.. _warehouse.pypa.io: https://warehouse.pypa.io
+.. _reStructuredText: https://docutils.sourceforge.io/rst.html
+.. _Markdown: https://www.markdownguide.org/
+.. _MyST: https://myst-parser.readthedocs.io/en/latest/
+.. _Sphinx: https://www.sphinx-doc.org/
+
+.. _dev-docs-layout:
+
+Layout
+------
+
+The developer documentation is located in the ``docs/dev`` directory.
+
+.. _dev-docs-local-dev:
+
+Local development
+-----------------
+
+To run a single local build of the dev docs, you can use the ``dev-docs``
+Makefile target:
+
+.. code-block:: console
+
+    make dev-docs
+
+That will produce a local build under ``docs/dev/_build/``.
+
+To run a local development server, you can use ``docker compose``:
+
+.. code-block:: console
+
+    docker compose up dev-docs
+
+Once running, you can visit a local build of the pages at `localhost:10002`_.
+
+.. _localhost\:10002: http://localhost:10002
+
+User documentation
+==================
+
+The user documentation is hosted at `docs.pypi.org`_. It's written in
+`Markdown`_ and built using `MkDocs`_.
+
+.. _docs.pypi.org: https://docs.pypi.org
+.. _MkDocs: https://www.mkdocs.org/
+
+.. _user-docs-layout:
+
+Layout
+------
+
+The user documentation is located in the ``docs/user`` directory.
+
+.. _user-docs-local-dev:
+
+Local development
+-----------------
+
+To run a single local build of the user docs, you can use the ``user-docs``
+Makefile target:
+
+.. code-block:: console
+
+    make user-docs
+
+That will produce a local build under ``docs/user-site/``.
+
+To run a local development server, you can use ``docker compose``:
+
+.. code-block:: console
+
+    docker compose up user-docs
+
+Once running, you can visit a local build of the user documentation at `localhost:10000`_.
+
+.. _localhost\:10000: http://localhost:10000
+
+PyPI blog
+=========
+
+The PyPI blog is hosted at `blog.pypi.org`_. Like the user documentation,
+it's written in `Markdown`_ and built using `MkDocs`_.
+
+.. _blog.pypi.org: https://blog.pypi.org
+
+.. _blog-layout:
+
+Layout
+------
+
+The blog is located in the ``docs/blog`` directory.
+
+.. _blog-local-dev:
+
+Local development
+-----------------
+
+To run a single local build of the blog, you can use the ``blog``
+Makefile target:
+
+.. code-block:: console
+
+    make blog
+
+That will produce a local build under ``docs/blog-site/``.
+
+To run a local development server, you can use ``docker compose``:
+
+.. code-block:: console
+
+    docker compose up blog
+
+Once running, you can visit a local build of the blog at `localhost:10001`_.
+
+.. _localhost\:10001: http://localhost:10001

docs/dev/development/getting-started.rst

@@ -747,38 +747,6 @@ formatting and linting. You can reformat with:
 
     make reformat
 
-.. _build-docs:
-
-Building documentation
-----------------------
-
-The Warehouse documentation is stored in the :file:`docs/`
-directory with three subdirectories: blog, dev and user.
-Development docs (in the dev directory) are written in
-`reStructured Text`_ and rendered using `Sphinx`_. User docs ``/user``
-are written in markdown and rendered using ``mkdocs``. The blog is
-also written in markdown.
-
-Use :command:`make` to build the documentation. For example:
-
-.. code-block:: console
-
-    make user-docs dev-docs
-
-The HTML index for the user documentation can now be found at
-:file:`docs/user-site/index.html`, and the index for the developer
-documentation at :file:`docs/dev/_build/html/index.html`.
-
-Building the docs requires Python 3.8. If it is not installed, the
-:command:`make` command will give the following error message:
-
-.. code-block:: console
-
-  make: python3.8: Command not found
-  Makefile:53: recipe for target '.state/env/pyvenv.cfg' failed
-  make: *** [.state/env/pyvenv.cfg] Error 127
-
-
 .. _building-translations:
 
 Building translations

docs/dev/development/index.rst

@@ -38,6 +38,7 @@ Get involved or find help using:
     cloud
     email
     token-scanning
+    documentation
 
 .. _`GitHub`: https://github.com/pypi/warehouse
 .. _`"What to put in your bug report"`: https://www.contribution-guide.org/#what-to-put-in-your-bug-report