Create the Python Docs Editorial Board static site using Hugo (#13)

Features: - search box - Archives - RSS feed at /index.xml Add custom css so links are underlined.
python · Aug 23, 2024 · 9b8ea26 · 9b8ea26
1 parent 7fa1a96
commit 9b8ea26
Show file tree

Hide file tree

Showing 19 changed files with 376 additions and 46 deletions.
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ We have a "changelog" of decisions: [CHANGELOG.md](CHANGELOG.md).
 
 These updates provide high level information about the Editorial Board's activities:
 
-- [2024-01](updates/2024-01-08-editorial-board-update.md)
+- [2024-01](content/updates/2024-01-08-editorial-board-update.md)
 
 ## Process
 
@@ -34,3 +34,45 @@ These links give context on existing documentation landing pages:
 - [CPython Documentation Landing page (docs.python.org)](https://docs.python.org)
 - [PSF (python.org) website landing page](https://python.org)
 - [Documentation Experience presentation - Review navigation of PSF website related to docs](https://docs.google.com/presentation/d/1ujDv8wViPvAMFAtYCRxSKh-CMUlbjcfVYitsqEI2Ios)
+
+
+## Writing new content
+
+Hugo is not needed to be installed in order to write a new meeting minutes.
+
+Write the meeting minutes a markdown file under ``content/updates/*.md``, commit, and
+create the pull request. A preview will then be generated on Netlify.
+
+The meeting minutes should be written using template provided in [archetypes/updates.md](/archetypes/updates.md).
+
+If you have Hugo installed, a new meeting minutes file can be created by typing on the command line:
+
+```
+hugo new content content/updates/newupdate.md
+```
+
+This will create the file under ``content/updates/newupdate.md``, and you can continue editing it.
+
+(replace "newupdate.md" with the desired filename.)
+
+## Building the static site locally
+
+1. First install Hugo.
+
+2. Run the command at the root of the repository:
+
+```
+hugo server
+```
+
+## Writing new changelog
+
+Use the template in [archetypes/changelog.md](archetypes/changelog.md).
+
+The file can also be created using the command:
+
+```
+hugo new content content/changelog/newchangelog.md
+```
+
+It will create a new file under ``content/changelog/newchangelog.md``. (Replace "newchangelog.md" with the desired filename).
diff --git a/archetypes/changelog.md b/archetypes/changelog.md
@@ -0,0 +1,10 @@
+---
+author: [""]
+title: "Changelog: {{ .Date | dateFormat "Jan 2, 2006" }}"
+date: "{{ .Date }}"
+tags: ["changelog"]
+categories: ["changelog"]
+series: ["Changelog"]
+ShowToc: false
+TocOpen: false
+---
diff --git a/archetypes/default.md b/archetypes/default.md
@@ -0,0 +1,5 @@
+---
+title: ""
+date: "{{ .Date }}"
+---
+
diff --git a/archetypes/updates.md b/archetypes/updates.md
@@ -0,0 +1,20 @@
+---
+author: [""]
+title: "Meeting Minutes: {{ .Date | dateFormat "Jan 2, 2006" }}"
+date: "{{ .Date }}"
+description: "Meeting Minutes from Python Docs Editorial Board: {{ .Date | dateFormat "Jan 2, 2006" }}"
+summary: "Meeting Minutes from Python Docs Editorial Board: {{ .Date | dateFormat "Jan 2, 2006" }}"
+tags: ["minutes"]
+categories: ["minutes"]
+series: ["Meeting Minutes"]
+ShowToc: false
+TocOpen: false
+---
+
+
+### Attendees
+
+### Agenda
+
+
+
diff --git a/assets/css/extended/custom.css b/assets/css/extended/custom.css
@@ -0,0 +1,23 @@
+.entry-content{
+    a{
+        text-decoration: underline;
+    }
+}
+
+#menu a{
+    :not(.active) {
+        text-decoration: underline;
+    }
+}
+
+.entry-header {
+    text-decoration: underline;
+}
+
+.archive-entry h3{
+    text-decoration: underline;
+}
+
+.breadcrumbs a:hover{
+    text-decoration: underline;
+}
diff --git a/content/archives.md b/content/archives.md
@@ -0,0 +1,6 @@
+---
+title: "Archive"
+layout: "archives"
+url: "/archives"
+summary: "archives"
+---
diff --git a/content/changelog/2024-07-12-function-signatures.md b/content/changelog/2024-07-12-function-signatures.md
@@ -0,0 +1,12 @@
+---
+author: ["Ned Batchelder"]
+title: "Changelog: July 12, 2024"
+date: "2024-07-12"
+tags: ["changelog"]
+categories: ["changelog"]
+series: ["Changelog"]
+ShowToc: false
+TocOpen: false
+---
+
+Function signatures should include slash and star: https://github.com/python/devguide/pull/1344
diff --git a/content/changelog/2024-07-18-clarify-timezone.md b/content/changelog/2024-07-18-clarify-timezone.md
@@ -0,0 +1,12 @@
+---
+author: ["Ned Batchelder"]
+title: "Changelog: July 18, 2024"
+date: "2024-07-18"
+tags: ["changelog"]
+categories: ["changelog"]
+series: ["Changelog"]
+ShowToc: false
+TocOpen: false
+---
+
+Clarify `timezone` vs "time zone": https://github.com/python/devguide/pull/1352
diff --git a/content/changelog/_index.md b/content/changelog/_index.md
@@ -0,0 +1,7 @@
+---
+title: "Editorial Board Decisions"
+---
+
+Editorial Board Decisions
+
+This is a running log of decisions taken by the Editorial Board.
diff --git a/content/search.md b/content/search.md
@@ -0,0 +1,5 @@
+---
+title: "Search"
+placeholder: Search demo site with full text fuzzy search ...
+layout: "search"
+---
diff --git a/updates/2024-01-08-editorial-board-update.md → ...ates/2024-01-08-editorial-board-update.md b/updates/2024-01-08-editorial-board-update.md → ...ates/2024-01-08-editorial-board-update.md
@@ -1,24 +1,35 @@
-# Meeting Notes: Python Docs Editorial Board
+---
+author: ["Carol Willing"]
+title: "Meeting Minutes: January 8, 2024"
+date: "2024-01-08"
+description: "Meeting Minutes from Python Docs Editorial Board: January 8, 2024."
+summary: "Meeting Minutes from Python Docs Editorial Board: January 8, 2024."
+tags: ["minutes"]
+categories: ["minutes"]
+series: ["Meeting Minutes"]
+ShowToc: false
+TocOpen: false
+---
 
-## January 8, 2024
 
-## Attendees
+
+### Attendees
 
 Carol, Guido, Joanna, Mariatta, Ned
 
-## Agenda
+### Agenda
 
 We discussed these questions and worked to answer them.
 
-### How often will we meet?
+#### How often will we meet?
 
 We will meet monthly on second Monday each month from 1:30-2:30pm Pacific.
 
 We will work asynchronously most of the time.
 
 Next meeting: February 12, 2024
 
-### What are our deliverables about process and decisions?
+#### What are our deliverables about process and decisions?
 
 We will produce:
 
@@ -36,24 +47,24 @@ We will produce:
     * We should limit ourselves to docs.python.org
     * Share recommendations to python.org for changes about making sure on python.org docs will go to docs.python.org. Reduce multiple paths to wiki and doc landing pages other than docs.python.org when refering to "docs"
 
-### Will we start implementing the five-year plan partly outlined in the [Language Summit 2020 presentation](https://pyfound.blogspot.com/2020/04/cpython-documentation-next-5-years.html), or do we need to reassess and set a different direction?
+#### Will we start implementing the five-year plan partly outlined in the [Language Summit 2020 presentation](https://pyfound.blogspot.com/2020/04/cpython-documentation-next-5-years.html), or do we need to reassess and set a different direction?
 
 The goals mentioned in the first and second years sound great, but I think we should review and see what we want to tackle first.  It could be those goals, or other ones, or a mix.
 
-#### *Year 1 goals (from old presentation)*
+##### *Year 1 goals (from old presentation)*
 
 * Governance and Workgroup: In progress; TODO: define how we work
 * Tutorials: Discussion started about existing tutorial. TODO: Do we have one "official" tutorial? Pathways for getting started (relates to landing page)
 * Language Translations: Seems to be going well; TODO: Identify any PyCon sprint focus areas
 * Landing Page: Work in progress [Documentation Experience presentation](https://docs.google.com/presentation/d/1ujDv8wViPvAMFAtYCRxSKh-CMUlbjcfVYitsqEI2Ios/edit#slide=id.p) TODO: Work with PSF to remove links to old wiki. This is for many the first stop in finding Python docs.
 
-#### *Year 2 and beyond goals (from old presentation)*
+##### *Year 2 and beyond goals (from old presentation)*
 
 * Evaluate effectiveness
 * Documentation sprints
 * Annual editorial review
 
-#### Selected priorities for the Editorial Board
+##### Selected priorities for the Editorial Board
 
 * How we can make it easier for people to contribute to docs
 * How to make the docs even more accessible
@@ -68,7 +79,7 @@ The goals mentioned in the first and second years sound great, but I think we sh
 
 **Decisions about documentation can be undone more easily than with code.**
 
-### How will we stay in touch with the docs community?
+#### How will we stay in touch with the docs community?
 
 Some people have already asked how they can be involved.
 
@@ -94,7 +105,7 @@ We discussed the following process considerations:
   * Any further discussions to continue on the Discourse, or privately by the Editorial Board.
   * There is no further discussions/comments on the repo's issue.
 
-### What are the things that require the Editorial Board to act on?
+#### What are the things that require the Editorial Board to act on?
 
 * Conflicts on content
 * Conflicts on tone and style best practices
@@ -104,7 +115,7 @@ We discussed the following process considerations:
 * Provide guidance and guidelines for changes
   See for example, the recent pull request: [https://github.com/python/cpython/pull/107449/files](https://github.com/python/cpython/pull/107449/files) which touches on global style issues.
 
-## Action items
+### Action items
 
 * Contact PSF infra/PSF board about python.org.
 * Create a REPO similar to steering-council: python/editorial-board
@@ -116,7 +127,7 @@ We discussed the following process considerations:
     * 1. Proposing a new idea
     * 2. We need a decision of existing issue.
 
-## Resources
+### Resources
 
 These links give context on the editorial board:
 

diff --git a/updates/2024-02-12-editorial-board-update.md → ...ates/2024-02-12-editorial-board-update.md b/updates/2024-02-12-editorial-board-update.md → ...ates/2024-02-12-editorial-board-update.md
@@ -1,6 +1,15 @@
-# Meeting Notes: Python Docs Editorial Board
-
-## February 12, 2024
+---
+author: ["Mariatta"]
+title: "Meeting Minutes: February 12, 2024"
+date: "2024-02-12"
+description: "Meeting Minutes from Python Docs Editorial Board: February 12, 2024."
+summary: "Meeting Minutes from Python Docs Editorial Board: February 12, 2024."
+tags: ["minutes"]
+categories: ["minutes"]
+series: ["Meeting Minutes"]
+ShowToc: false
+TocOpen: false
+---
 
 ## Attendees
 

diff --git a/updates/2024-03-11-editorial-board-update.md → ...ates/2024-03-11-editorial-board-update.md b/updates/2024-03-11-editorial-board-update.md → ...ates/2024-03-11-editorial-board-update.md
@@ -1,13 +1,23 @@
-# Meeting Notes: Python Docs Editorial Board
-
-## March 11, 2024
-
-## Attendees
+---
+author: ["Mariatta"]
+title: "Meeting Minutes: March 11, 2024"
+date: "2024-03-11"
+description: "Meeting Minutes from Python Docs Editorial Board: March 11, 2024."
+summary: "Meeting Minutes from Python Docs Editorial Board: March 11, 2024."
+tags: ["minutes"]
+categories: ["minutes"]
+series: ["Meeting Minutes"]
+ShowToc: false
+TocOpen: false
+---
+
+
+### Attendees
 
 Mariatta, Ned, Joanna, Guido
 
 
-## Agenda
+### Agenda
 
 1. What project do we want to deliver first? Here are some ideas to start the discussion:
 
@@ -40,7 +50,7 @@ Mariatta, Ned, Joanna, Guido
 
 
 
-## Notes
+### Notes
 
 Guido: We didn't actually go through that agenda at all.
 We discuss what our priorities are.

diff --git a/updates/2024-04-08-editorial-board-update.md → ...ates/2024-04-08-editorial-board-update.md b/updates/2024-04-08-editorial-board-update.md → ...ates/2024-04-08-editorial-board-update.md
@@ -1,13 +1,23 @@
-# Meeting Notes: Python Docs Editorial Board
+---
+author: ["Mariatta"]
+title: "Meeting Minutes: April 08, 2024"
+date: "2024-04-08"
+description: "Meeting Minutes from Python Docs Editorial Board: April 08, 2024."
+summary: "Meeting Minutes from Python Docs Editorial Board: April 08, 2024."
+tags: ["minutes"]
+categories: ["minutes"]
+series: ["Meeting Minutes"]
+ShowToc: false
+TocOpen: false
+---
 
-## April 8, 2024
 
-## Attendees
+### Attendees
 
 Mariatta, Ned, Joanna, Guido
 
 
-## Agenda
+### Agenda
 
 1. What will be our Doc Summit participation?
    - Who will be attending? Carol, Ned

diff --git a/updates/2024-06-03-editorial-board-update.md → ...ates/2024-06-03-editorial-board-update.md b/updates/2024-06-03-editorial-board-update.md → ...ates/2024-06-03-editorial-board-update.md
@@ -1,13 +1,23 @@
-# Meeting Notes: Python Docs Editorial Board
-
-## June 3, 2024
-
-## Attendees
+---
+author: ["Mariatta"]
+title: "Meeting Minutes: June 03, 2024"
+date: "2024-06-03"
+description: "Meeting Minutes from Python Docs Editorial Board: June 03, 2024."
+summary: "Meeting Minutes from Python Docs Editorial Board: June 03, 2024."
+tags: ["minutes"]
+categories: ["minutes"]
+series: ["Meeting Minutes"]
+ShowToc: false
+TocOpen: false
+---
+
+
+### Attendees
 
 Mariatta, Ned, Carol, Joanna, Guido
 
 
-## Old Action Items
+### Old Action Items
 
 Where are we with the action items from April 8?
 
@@ -32,7 +42,7 @@ Where are we with the action items from March 11?
 3. Document our philosophy, explain the different target users and where they can find the docs they need.
 
 
-## Agenda
+### Agenda
 
 1. What action items are we taking from the discussion at the docs dinner?
    * Notes on contributing to docs: