skeleton for user-docs

.readthedocs.yml

@@ -5,13 +5,7 @@
 # Required
 version: 2
 
-# Change the default requirements file
-python:
-  install:
-    - requirements: requirements/docs.txt
-
-# Use the same version of Python we use here
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.11"

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 mkdocs.yml

docker-compose.yml

@@ -91,6 +91,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
@@ -179,3 +180,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.yml
+    volumes:
+      - ./mkdocs.yml:/opt/warehouse/src/mkdocs.yml:z
+      - ./user-docs:/opt/warehouse/src/user-docs:z
+    ports:
+      - "10000:8000"

mkdocs.yml

@@ -0,0 +1,16 @@
+site_name: PyPI Docs
+docs_dir: user-docs
+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

requirements/user-docs.in

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

user-docs/.gitignore

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

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/stylesheets/extra.css

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