Standup our user-docs for https://docs.pypi.org/

.readthedocs.yml

@@ -4,14 +4,27 @@
 
 # Required
 version: 2
-
-# Change the default requirements file
 python:
   install:
     - requirements: requirements/docs.txt
+# When https://github.com/readthedocs/readthedocs.org/pull/10119 is deployed to readthedocs, this can be uncommented
+#   - requirements: requirements/user-docs.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.txt -r /tmp/requirements/user-docs.txt'; fi) \
     && pip check \
     && find /opt/warehouse -name '*.pyc' -delete
 

Makefile

@@ -71,6 +71,9 @@ lint: .state/docker-build-web
 docs: .state/docker-build-web
 	docker compose run --rm web bin/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
 

bin/user-docs

@@ -0,0 +1,13 @@
+#!/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
+
+mkdocs build -f user-docs/mkdocs.yml

docker-compose.yml

@@ -92,6 +92,7 @@ services:
       # permissive security context.
       - ./dev:/opt/warehouse/src/dev:z
       - ./docs:/opt/warehouse/src/docs:z
+      - ./user-docs:/opt/warehouse/src/user-docs:z
       - ./warehouse:/opt/warehouse/src/warehouse:z
       - ./tests:/opt/warehouse/src/tests:z
       - ./htmlcov:/opt/warehouse/src/htmlcov:z
@@ -185,3 +186,14 @@ 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 user-docs/mkdocs.yml
+    volumes:
+      - ./user-docs:/opt/warehouse/src/user-docs:z
+    ports:
+      - "10000:8000"

requirements/user-docs.in

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

user-docs/.gitignore

@@ -0,0 +1 @@
+./site

user-docs/REAME.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.

user-docs/index.md

@@ -0,0 +1,17 @@
+# Welcome to MkDocs
+
+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.

user-docs/mkdocs.yml

@@ -0,0 +1,16 @@
+site_name: PyPI Docs
+docs_dir: .
+theme:
+  name: material
+  logo: assets/logo.png
+  favicon: assets/favicon.ico
+  homepage: https://pypi.org
+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

user-docs/stylesheets/extra.css

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