create a blog (#13231)

* create a blog

* developer experience

* try to fancy it

* Fix blog rendering

* Posts should have relative URLs

* Fixup fix

* Separate link to homepage from blog

* Hide site_name from nav

* Highlight index in nav

* Properly render blog content

* Fix typo

* Remove author_gh_user

* Remove .git volume

* Move custom styles

* Remove unnecessary volume

* Remove test blog post

* Add the mkdocs social plugin

* Clean up formatting around authors and descriptions

* Extend linting to blog

* Write an actual blog post!

* doin a blerg

---------

Co-authored-by: Dustin Ingram <[email protected]>

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/dev.txt -r /tmp/requirements/docs/user.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 -r /tmp/requirements/docs/blog.txt'; fi) \
     && pip check \
     && find /opt/warehouse -name '*.pyc' -delete
 
@@ -132,7 +132,7 @@ RUN set -x \
     && apt-get update \
     && apt-get install --no-install-recommends -y \
         libpq5 libxml2 libxslt1.1 libcurl4  \
-        $(if [ "$DEVEL" = "yes" ]; then echo 'bash libjpeg62 postgresql-client build-essential libffi-dev libxml2-dev libxslt-dev libpq-dev libcurl4-openssl-dev libssl-dev'; fi) \
+        $(if [ "$DEVEL" = "yes" ]; then echo 'bash libjpeg62 postgresql-client build-essential libffi-dev libxml2-dev libxslt-dev libpq-dev libcurl4-openssl-dev libssl-dev git libcairo2-dev libfreetype6-dev libjpeg-dev libpng-dev libz-dev'; fi) \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 

Makefile

@@ -74,6 +74,9 @@ dev-docs: .state/docker-build-web
 user-docs: .state/docker-build-web
 	docker-compose run --rm web bin/user-docs
 
+blog: .state/docker-build-web
+	docker-compose run --rm web bin/blog
+
 licenses: .state/docker-build-web
 	docker compose run --rm web bin/licenses
 

bin/blog

@@ -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 docs/blog.yml

bin/lint

@@ -17,5 +17,5 @@ python -m flake8 .
 python -m black --check *.py warehouse/ tests/
 python -m isort --check *.py warehouse/ tests/
 python -m doc8 --allow-long-titles README.rst CONTRIBUTING.rst docs/ --ignore-path "docs/**/_build/"
-python -m curlylint ./warehouse/templates
+python -m curlylint ./warehouse/templates ./docs/blog
 python -m mypy -p warehouse

bin/rtd-docs

@@ -10,9 +10,17 @@ if [ "${READTHEDOCS_PROJECT}" = "warehouse" ]; then
   make -C docs/dev/ html
   mkdir _readthedocs && mv docs/dev/_build/html _readthedocs/html
 fi
+
 if [ "${READTHEDOCS_PROJECT}" = "docspypiorg" ]; then
   pip install -r requirements/docs/user.txt
   asdf reshim
   mkdocs build -f mkdocs-user-docs.yml
   mkdir _readthedocs && mv docs/user-site _readthedocs/html
 fi
+
+if [ "${READTHEDOCS_PROJECT}" = "blogpypiorg" ]; then
+  pip install -r requirements/docs/blog.txt
+  asdf reshim
+  mkdocs build -f docs/blog.yml
+  mkdir _readthedocs && mv docs/blog-site _readthedocs/html
+fi

docker-compose.yml

@@ -92,8 +92,6 @@ 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
@@ -189,13 +187,21 @@ services:
       - "8964:8000"
 
   user-docs:
-    build:
-      context: .
-      args:
-        DEVEL: "yes"
+    image: warehouse:docker-compose
     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"
+    depends_on: [web]
+
+  blog:
+    image: warehouse:docker-compose
+    command: mkdocs serve -a 0.0.0.0:8000 -f docs/blog.yml
+    volumes:
+      - ./docs/blog.yml:/opt/warehouse/src/docs/blog.yml:z
+      - ./docs/blog:/opt/warehouse/src/docs/blog:z
+    ports:
+      - "10001:8000"
+    depends_on: [web]

docs/.gitignore

@@ -1 +1,2 @@
 user-site
+blog-site

docs/blog.yml

@@ -0,0 +1,36 @@
+site_name: The Python Package Index
+site_description: The official blog of the Python Package Index
+docs_dir: blog
+site_dir: blog-site
+theme:
+  name: material
+  logo: assets/logo.png
+  favicon: assets/favicon.ico
+  homepage: https://pypi.org
+  custom_dir: blog/overrides
+markdown_extensions:
+  - footnotes
+extra_css:
+  - stylesheets/extra.css
+plugins:
+  - social
+  - blogging:
+      dirs:
+        - posts
+      template: blog/overrides/pypi-blog.html
+      features:
+        tags:
+          index_page: tags.md
+          insert: top
+      locale: en         # The locale for time localizations, default: system's locale
+      time_format: '%Y-%m-%d %H:%M:%S' # The format used to display the time
+      meta_time_format: '%Y-%m-%d %H:%M:%S' # The format used to parse the time from meta
+extra:
+  homepage: https://pypi.org
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/pypi
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/pypi
+site_url: https://blog.pypi.org/
+repo_url: https://github.com/pypi/warehouse

docs/blog/README.md

@@ -0,0 +1,22 @@
+# PyPI Blog
+
+This blog is hosted at https://blog.pypi.org/ to provide a way for the PyPI
+Administrators to share new features, breaking changes, and curiosities with
+the community.
+
+Posts are written in [Markdown](https://www.markdownguide.org) and built using
+[mkdocs](https://www.mkdocs.org).
+
+The blog is built and deployed with [readthedocs.org](https://readthedocs.org/projects/blogpypiorg/).
+
+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 blog` 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/blog/index.md

@@ -0,0 +1,7 @@
+---
+exclude_from_blog: true
+---
+
+# The PyPI Blog
+
+{{ blog_content }}

docs/blog/overrides/partials/content.html

@@ -0,0 +1,61 @@
+<!--
+  Copyright (c) 2016-2023 Martin Donath <[email protected]>
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to
+  deal in the Software without restriction, including without limitation the
+  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+  sell copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+  IN THE SOFTWARE.
+-->
+
+<!-- Tags -->
+{% if "material/tags" in config.plugins %}
+  {% include "partials/tags.html" %}
+{% endif %}
+
+<!-- Actions -->
+{% include "partials/actions.html" %}
+
+<!--
+  Hack: check whether the content contains a h1 headline. If it doesn't, the
+  page title (or respectively site name) is used as the main headline.
+-->
+{% if "\x3ch1" not in page.content %}
+  <h1>{{ page.title | d(config.site_name, true)}}</h1>
+{% endif %}
+
+{% if "author" in page.meta %}
+  by: <b>{{ page.meta["author"] + " · " if "publish_date" in page.meta else "" }}</b>
+{% endif %}
+{% if "publish_date" in page.meta %}
+  <span>{{ page.meta["publish_date"] }}</span>
+{% endif %}
+
+<!-- Page content -->
+{{ page.content }}
+
+<!-- Source file information -->
+{% if page.meta and (
+  page.meta.git_revision_date_localized or
+  page.meta.revision_date
+) %}
+  {% include "partials/source-file.html" %}
+{% endif %}
+
+<!-- Was this page helpful? -->
+{% include "partials/feedback.html" %}
+
+<!-- Comment system -->
+{% include "partials/comments.html" %}