Create user facing documentation structure

.github/workflows/ci.yml

@@ -20,8 +20,10 @@ jobs:
             command: bin/tests --postgresql-host localhost
           - name: Lint
             command: bin/lint
-          - name: Documentation
-            command: bin/docs
+          - name: User Documentation
+            command: bin/user-docs
+          - name: Developer Documentation
+            command: bin/dev-docs
           - name: Dependencies
             command: bin/github-actions-deps
           - name: Licenses

.gitignore

@@ -10,7 +10,8 @@
 .idea
 .envrc
 
-docs/_build/
+docs/dev/_build/
+docs/user/_build/
 build/
 dist/*.tar.gz
 dist/*.whl

.readthedocs.yml

@@ -4,14 +4,27 @@
 
 # Required
 version: 2
-
-# Change the default requirements file
 python:
   install:
-    - requirements: requirements/docs.txt
+    - requirements: requirements/docs/dev.txt
+# When https://github.com/readthedocs/readthedocs.org/pull/10119 is deployed to readthedocs, this can be uncommented
+#   - requirements: requirements/docs/user.txt
 
-# Use the same version of Python we use here
 build:
   os: ubuntu-20.04
   tools:
-    python: "3.10"
+    python: "3.11"
+# When https://github.com/readthedocs/readthedocs.org/pull/10119 is deployed to readthedocs, this can be uncommented
+#  commands:
+#    - |
+#        if [ "$READTHEDOCS_PROJECT" = "warehouse" ]
+#        then
+#          make -C docs/ html;
+#          mv docs/_build/html _readthedocs/html;
+#        fi
+#    - |
+#        if [ "$READTHEDOCS_PROJECT" = "docspypiorg" ]
+#        then
+#          mkdocs build -f user-docs/mkdocs.yml;
+#          mv user-docs/site _readthedocs/html;
+#        fi

Dockerfile

@@ -96,7 +96,7 @@ RUN set -x \
             install --no-deps \
                     -r /tmp/requirements/deploy.txt \
                     -r /tmp/requirements/main.txt \
-                    $(if [ "$DEVEL" = "yes" ]; then echo '-r /tmp/requirements/tests.txt -r /tmp/requirements/lint.txt -r /tmp/requirements/docs.txt'; fi) \
+                    $(if [ "$DEVEL" = "yes" ]; then echo '-r /tmp/requirements/tests.txt -r /tmp/requirements/lint.txt -r /tmp/requirements/docs/dev.txt -r /tmp/requirements/docs/user.txt'; fi) \
     && pip check \
     && find /opt/warehouse -name '*.pyc' -delete
 

Makefile

@@ -17,7 +17,7 @@ default:
 	@echo
 	@exit 1
 
-.state/docker-build-web: Dockerfile package.json package-lock.json requirements/main.txt requirements/deploy.txt requirements/lint.txt requirements/docs.txt requirements/dev.txt requirements/tests.txt
+.state/docker-build-web: Dockerfile package.json package-lock.json requirements/main.txt requirements/deploy.txt requirements/lint.txt requirements/docs/dev.txt requirements/docs/user.txt requirements/dev.txt requirements/tests.txt
 	# Build our web container for this project.
 	docker compose build --build-arg IPYTHON=$(IPYTHON) --force-rm web
 
@@ -68,8 +68,11 @@ lint: .state/docker-build-web
 	docker compose run --rm web bin/lint
 	docker compose run --rm static bin/static_lint
 
-docs: .state/docker-build-web
-	docker compose run --rm web bin/docs
+dev-docs: .state/docker-build-web
+	docker compose run --rm web bin/dev-docs
+
+user-docs: .state/docker-build-web
+	docker-compose run --rm web bin/user-docs
 
 licenses: .state/docker-build-web
 	docker compose run --rm web bin/licenses
@@ -110,4 +113,4 @@ purge: stop clean
 stop:
 	docker compose down -v
 
-.PHONY: default build serve initdb shell tests docs deps clean purge debug stop compile-pot
+.PHONY: default build serve initdb shell tests dev-docs user-docs deps clean purge debug stop compile-pot

bin/dev-docs

@@ -0,0 +1,14 @@
+#!/bin/bash
+set -e
+
+# Click requires us to ensure we have a well configured environment to run
+# our click commands. So we'll set our environment to ensure our locale is
+# correct.
+export LC_ALL="${ENCODING:-en_US.UTF-8}"
+export LANG="${ENCODING:-en_US.UTF-8}"
+
+# Print all the following commands
+set -x
+
+make -C docs/dev/ doctest SPHINXOPTS="-W"
+make -C docs/dev/ html SPHINXOPTS="-W"

bin/docs → bin/user-docs

@@ -10,5 +10,4 @@ export LANG="${ENCODING:-en_US.UTF-8}"
 # Print all the following commands
 set -x
 
-make -C docs/ doctest SPHINXOPTS="-W"
-make -C docs/ html SPHINXOPTS="-W"
+mkdocs build -f mkdocs-user-docs.yml

docker-compose.yml

@@ -92,6 +92,8 @@ services:
       # permissive security context.
       - ./dev:/opt/warehouse/src/dev:z
       - ./docs:/opt/warehouse/src/docs:z
+      - ./mkdocs-user-docs.yml:/opt/warehouse/src/mkdocs-user-docs.yml:z
+      - ./docs/user:/opt/warehouse/src/docs/user:z
       - ./warehouse:/opt/warehouse/src/warehouse:z
       - ./tests:/opt/warehouse/src/tests:z
       - ./htmlcov:/opt/warehouse/src/htmlcov:z
@@ -185,3 +187,15 @@ services:
       NOTGITHUB_DEFAULT_URL: "http://web:8000/_/github/disclose-token"
     ports:
       - "8964:8000"
+
+  user-docs:
+    build:
+      context: .
+      args:
+        DEVEL: "yes"
+    command: mkdocs serve -a 0.0.0.0:8000 -f mkdocs-user-docs.yml
+    volumes:
+      - ./mkdocs-user-docs.yml:/opt/warehouse/src/mkdocs-user-docs.yml:z
+      - ./docs/user:/opt/warehouse/src/docs/user:z
+    ports:
+      - "10000:8000"

docs/.gitignore

@@ -0,0 +1 @@
+user-site

docs/user/README.md

@@ -0,0 +1,21 @@
+# PyPI User Facing Documentation
+
+This documentation is (will be) hosted at https://docs.pypi.org/ to provide
+user-facing documentation for using PyPI.
+
+Documentation is written in [Markdown](https://www.markdownguide.org) and built
+using [mkdocs](https://www.mkdocs.org).
+
+The documentation is (will be) built and deployed with [readthedocs.org](https://readthedocs.org/projects/docspypiorg/).
+
+See our [`.readthedocs.yml`](../.readthedocs.yml) for configuration.
+
+## Setup
+
+After following the [installation instructions](https://warehouse.pypa.io/development/getting-started.html#detailed-installation-instructions)
+all the remaining commands take place in containers.
+
+The project can be previewed by running `docker compose up user-docs` from the
+base directory of your clone of pypa/warehouse. This will start a `mkdocs`
+development server that will live reload as you change the contents of this
+directory, including the `mkdocs.yml` configuration.

docs/user/index.md

@@ -0,0 +1,17 @@
+# Welcome to PyPI
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

docs/user/stylesheets/extra.css

@@ -0,0 +1,3 @@
+:root {
+  --md-primary-fg-color: #0073b7;
+}

mkdocs-user-docs.yml

@@ -0,0 +1,21 @@
+site_name: PyPI Docs
+docs_dir: docs/user
+site_dir: docs/user-site
+theme:
+  name: material
+  logo: assets/logo.png
+  favicon: assets/favicon.ico
+  homepage: https://pypi.org
+  features:
+    - content.action.edit
+extra_css:
+  - stylesheets/extra.css
+extra:
+  homepage: https://pypi.org
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/pypi
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/pypi
+repo_url: https://github.com/pypi/warehouse
+edit_uri: blob/main/docs/user/

requirements.txt

@@ -1,6 +1,7 @@
 # This is only used for dependabot and Github Actions CI
 -r requirements/main.txt
 -r requirements/deploy.txt
--r requirements/docs.txt
+-r requirements/docs/dev.txt
+-r requirements/docs/user.txt
 -r requirements/lint.txt
 -r requirements/tests.txt

requirements/docs.txt → requirements/docs/dev.txt

@@ -2,7 +2,7 @@
 # This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
-#    pip-compile --allow-unsafe --generate-hashes --output-file=requirements/docs.txt requirements/docs.in
+#    pip-compile --allow-unsafe --generate-hashes --output-file=requirements/docs/dev.txt requirements/docs/dev.in
 #
 alabaster==0.7.13 \
     --hash=sha256:1ee19aca801bbabb5ba3f5f258e4422dfa86f82f3e9cefb0859b283cdd7f62a3 \
@@ -119,7 +119,7 @@ docutils==0.19 \
 furo==2022.12.7 \
     --hash=sha256:7cb76c12a25ef65db85ab0743df907573d03027a33631f17d267e598ebb191f7 \
     --hash=sha256:d8008f8efbe7587a97ba533c8b2df1f9c21ee9b3e5cad0d27f61193d38b1a986
-    # via -r requirements/docs.in
+    # via -r requirements/docs/dev.in
 idna==3.4 \
     --hash=sha256:814f528e8dead7d329833b91c5faa87d60bf71824cd12a7530b5526063d02cb4 \
     --hash=sha256:90b77e79eaa3eba6de819a0c442c0b4ceefc341a7a2ab77d7562bf49f425c5c2
@@ -203,12 +203,12 @@ mdurl==0.1.2 \
 myst-parser==0.19.1 \
     --hash=sha256:356b38aef29ed09144285ad222e5c3cb7a8e7fae8015d53dba40dbb8b9f73e2c \
     --hash=sha256:f2dc168ed380e01d77973ad22a64fff1377cc72a3d1ac4bced423f28258d0a42
-    # via -r requirements/docs.in
+    # via -r requirements/docs/dev.in
 packaging==21.3 \
     --hash=sha256:dd47c42927d89ab911e606518907cc2d3a1f38bbd026385970643f9c5b8ecfeb \
     --hash=sha256:ef103e05f519cdc783ae24ea4e2e0f508a9c99b2d4969652eed6a2e1ea5bd522
     # via
-    #   -r requirements/docs.in
+    #   -r requirements/docs/dev.in
     #   sphinx
 pygments==2.14.0 \
     --hash=sha256:b3ed06a9e8ac9a9aae5a6f5dbe78a8a58655d17b43b93c078f094ddc476ae297 \
@@ -282,7 +282,7 @@ sphinx==5.3.0 \
     --hash=sha256:060ca5c9f7ba57a08a1219e547b269fadf125ae25b06b9fa7f66768efb652d6d \
     --hash=sha256:51026de0a9ff9fc13c05d74913ad66047e104f56a129ff73e174eb5c3ee794b5
     # via
-    #   -r requirements/docs.in
+    #   -r requirements/docs/dev.in
     #   furo
     #   myst-parser
     #   sphinx-basic-ng
@@ -306,7 +306,7 @@ sphinxcontrib-htmlhelp==2.0.1 \
 sphinxcontrib-httpdomain==1.8.1 \
     --hash=sha256:21eefe1270e4d9de8d717cc89ee92cc4871b8736774393bafc5e38a6bb77b1d5 \
     --hash=sha256:6c2dfe6ca282d75f66df333869bb0ce7331c01b475db6809ff9d107b7cdfe04b
-    # via -r requirements/docs.in
+    # via -r requirements/docs/dev.in
 sphinxcontrib-jsmath==1.0.1 \
     --hash=sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178 \
     --hash=sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8

requirements/docs/user.in

@@ -0,0 +1,3 @@
+mkdocs
+mkdocs-material
+packaging<=21.3