Use custom syntax for jinja2 macros in docs (#13401)

* Fix local dev for docs * Use custom syntax for jinja2 macros in docs The current syntax (curly braces) causes conflicts with certain code samples we might want to include. Additionally, using curly braces has the downside of causing these to show up when the markdown is rendered outside of our docs (e.g. on GitHub). To avoid breakage and to ensure the docs render well on GitHub, we'll use a different start/end string for blocks and variables that also doubles as an HTML comment. This is documented here: https://github.com/fralau/mkdocs_macros_plugin/blob/2f1d86e3dea836c4d941926df4be41762dbf893a/webdoc/docs/advanced.md?plain=1#L252 * Remove unnecessary escaping * Add TODOs in org docs
pypi · Apr 10, 2023 · 3147bcb · 3147bcb
1 parent 4b954a2
commit 3147bcb
Show file tree

Hide file tree

Showing 15 changed files with 31 additions and 25 deletions.
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -198,10 +198,10 @@ services:
   user-docs:
     image: warehouse:docker-compose-docs
     pull_policy: never
-    command: mkdocs serve -a 0.0.0.0:8000 -f mkdocs-user-docs.yml
+    command: mkdocs serve -a 0.0.0.0:8000 -f docs/mkdocs-user-docs.yml
     volumes:
       - ./bin:/opt/warehouse/src/bin:z
-      - ./mkdocs-user-docs.yml:/opt/warehouse/src/mkdocs-user-docs.yml:z
+      - ./docs/mkdocs-user-docs.yml:/opt/warehouse/src/docs/mkdocs-user-docs.yml:z
       - ./docs:/opt/warehouse/src/docs:z
     ports:
       - "10000:8000"

diff --git a/docs/mkdocs-user-docs.yml b/docs/mkdocs-user-docs.yml
@@ -4,6 +4,10 @@ site_dir: user-site
 plugins:
   - macros:
       module_name: user/main
+      j2_block_start_string: '<!--[[%'
+      j2_block_end_string: '%]]-->'
+      j2_variable_start_string: '<!--[['
+      j2_variable_end_string: ']]-->'
 markdown_extensions:
   - admonition
   - pymdownx.details

diff --git a/docs/user/organization-accounts/actions/billing-actions.md b/docs/user/organization-accounts/actions/billing-actions.md
@@ -2,7 +2,7 @@
 title: Billing Actions
 ---
 
-{{ preview('org-accounts') }}
+<!--[[ preview('org-accounts') ]]-->
 
 # Billing actions
 

diff --git a/docs/user/organization-accounts/actions/org-actions.md b/docs/user/organization-accounts/actions/org-actions.md
@@ -2,7 +2,7 @@
 title: Organization Actions
 ---
 
-{{ preview('org-accounts') }}
+<!--[[ preview('org-accounts') ]]-->
 
 # Operations
 This section describes the actions that can be performed
@@ -28,7 +28,7 @@ a billing page will appear. Enter the billing details.
 
 Once the organization has been created, it will have to be
 approved by the PyPI admin.
-This usually takes <<>> days.
+This usually takes <<TODO>> days.
 Once the account request has been approved,
 the user who created the account becomes the Owner of the organization.
 The Owner will be able to manage the organization once it has been approved.

diff --git a/docs/user/organization-accounts/actions/project-actions.md b/docs/user/organization-accounts/actions/project-actions.md
@@ -2,7 +2,7 @@
 title: Project Actions
 ---
 
-{{ preview('org-accounts') }}
+<!--[[ preview('org-accounts') ]]-->
 
 # Project actions
 

diff --git a/docs/user/organization-accounts/actions/team-actions.md b/docs/user/organization-accounts/actions/team-actions.md
@@ -2,7 +2,7 @@
 title: Team Actions
 ---
 
-{{ preview('org-accounts') }}
+<!--[[ preview('org-accounts') ]]-->
 
 # Team actions
 This section describes the actions that can be performed within

diff --git a/docs/user/organization-accounts/index.md b/docs/user/organization-accounts/index.md
@@ -2,7 +2,7 @@
 title: About
 ---
 
-{{ preview('org-accounts') }}
+<!--[[ preview('org-accounts') ]]-->
 
 # PyPI Organization Accounts
 

diff --git a/docs/user/organization-accounts/org-acc-faq.md b/docs/user/organization-accounts/org-acc-faq.md
@@ -2,7 +2,7 @@
 title: FAQs
 ---
 
-{{ preview('org-accounts') }}
+<!--[[ preview('org-accounts') ]]-->
 
 # FAQs
 
@@ -11,7 +11,7 @@ This list of FAQs pertain to organization accounts in PyPI.
 1. **Can anyone create an organization account?**
 
     Yes, anyone can create an organization. For more information,
-    please see <<>>
+    please see <<TODO>>
 
 1. **How do I access an organization account?**
 
@@ -23,17 +23,20 @@ This list of FAQs pertain to organization accounts in PyPI.
     organization URL provided when creating the account
 
 1. **Why does an admin approve the organization account request?**
-
+
+    <<TODO>>
+
 1. **How many days does it take for the admin to approve the organization
 account request?**
 
-    It will take <<>> days for the account to be approved.
-    If the account has not been approved in <<>> days, please contact <<>>.
+    It will take <<TODO>> days for the account to be approved.
+    If the account has not been approved in <<TODO>> days, please contact
+    <<TODO>>.
 
 1. **What is the subscription fee?**
 
     The organization account subscription fee depends on the
-    number of users. <<>>
+    number of users. <<TODO>>
 
 1. **Do community projects like ‘warehouse’ have to pay a subscription fee?**
 
@@ -48,7 +51,7 @@ organization or community  project?**
 
 1. **Can we cancel a subscription?**
 
-    Yes, you can cancel a subscription. For more information, see <<>>.
+    Yes, you can cancel a subscription. For more information, see <<TODO>>.
 
 1. **Is there a trial period?**
 
@@ -57,7 +60,7 @@ organization or community  project?**
 1. **Can we renew a lapsed subscription?**
 
     Yes, it is possible to renew a subscription. For more information,
-    see << add link>>
+    see <<TODO: add link>>
 
 1. **What happens if a subscription fee is not paid?**
 

diff --git a/docs/user/organization-accounts/roles-entities.md b/docs/user/organization-accounts/roles-entities.md
@@ -2,7 +2,7 @@
 title: Roles and Entities
 ---
 
-{{ preview('org-accounts') }}
+<!--[[ preview('org-accounts') ]]-->
 
 # Roles and entities in an organization account
 

diff --git a/docs/user/trusted-publishers/adding-a-publisher.md b/docs/user/trusted-publishers/adding-a-publisher.md
@@ -2,7 +2,7 @@
 title: Adding a Trusted Publisher to an Existing PyPI Project
 ---
 
-{{ preview('oidc-publishing') }}
+<!--[[ preview('oidc-publishing') ]]-->
 
 # Adding a trusted publisher to an existing PyPI project
 

diff --git a/docs/user/trusted-publishers/creating-a-project-through-oidc.md b/docs/user/trusted-publishers/creating-a-project-through-oidc.md
@@ -2,7 +2,7 @@
 title: Creating a PyPI Project with a Trusted Publisher
 ---
 
-{{ preview('oidc-publishing') }}
+<!--[[ preview('oidc-publishing') ]]-->
 
 # Creating a PyPI project with a trusted publisher
 

diff --git a/docs/user/trusted-publishers/index.md b/docs/user/trusted-publishers/index.md
@@ -2,7 +2,7 @@
 title: Getting Started
 ---
 
-{{ preview('oidc-publishing') }}
+<!--[[ preview('oidc-publishing') ]]-->
 
 # Publishing to PyPI with a Trusted Publisher
 

diff --git a/docs/user/trusted-publishers/security-model.md b/docs/user/trusted-publishers/security-model.md
@@ -2,7 +2,7 @@
 title: Security Model and Considerations
 ---
 
-{{ preview('oidc-publishing') }}
+<!--[[ preview('oidc-publishing') ]]-->
 
 # Security model and considerations
 

diff --git a/docs/user/trusted-publishers/troubleshooting.md b/docs/user/trusted-publishers/troubleshooting.md
@@ -2,7 +2,7 @@
 title: Troubleshooting
 ---
 
-{{ preview('oidc-publishing') }}
+<!--[[ preview('oidc-publishing') ]]-->
 
 # Troubleshooting
 

diff --git a/docs/user/trusted-publishers/using-a-publisher.md b/docs/user/trusted-publishers/using-a-publisher.md
@@ -2,7 +2,7 @@
 title: Publishing with a Trusted Publisher
 ---
 
-{{ preview('oidc-publishing') }}
+<!--[[ preview('oidc-publishing') ]]-->
 
 # Publishing with a Trusted Publisher
 
@@ -49,7 +49,7 @@ flow, your diff might look like this:
          uses: pypa/gh-action-pypi-publish@release/v1
 -        with:
 -          username: __token__
--          password: {{ '${{ secrets.PYPI_TOKEN }}' }}
+-          password: ${{ secrets.PYPI_TOKEN }}
 ```
 
 Note the `id-token: write` permission: you **must** provide this permission
@@ -142,7 +142,6 @@ TWINE_USERNAME=__token__ TWINE_PASSWORD="${api_token}" twine upload dist/*
 This can all be tied together into a single GitHub Actions workflow:
 
 ```yaml
-
 on:
   release:
     types: