Reorg docs (#67)

* Reorg docs

* Feedback form tupui

doc/config.yaml

@@ -20,18 +20,22 @@ params:
   hero:
     title: Hugo Theme
     subtitle: Used by core projects in the scientific Python ecosystem.
-    buttontext: Go to docs
+    buttontext: Get started
     buttonlink: /getstarted/
     image: logo.svg
   navbar:
-    - title: GitHub
-      url: https://github.com/scientific-python/scientific-python-hugo-theme
+   - title: Features
+     url: /features/
+   - title: Shortcodes
+     url: /shortcodes/
   keyfeatures:
     features:
       - title: Documented
         text: The theme is documented at https://theme.scientific-python.org.
       - title: Reusable
-        text: The theme is being used by NumPy, SciPy, ...
+        text: "The theme is being used by [scientific-python.org](https://github.com/scientific-python/scientific-python.org),
+[numpy.org](https://github.com/numpy/numpy.org), and
+[scipy.org](https://github.com/scipy/scipy.org)."
       - title: Community Maintained
         text: The theme is maintained by the [Theme Team](https://github.com/orgs/scientific-python/teams/theme-team)
   footer:

doc/content/features.md

@@ -0,0 +1,82 @@
+---
+title: Features
+sidebar: true
+---
+
+## Partials
+
+The following partials are meant to be overridden:
+
+- `post_meta.html`: Render meta-data under a post title.
+                    We have not yet defined this template, but you can use it to add author information, date, etc.
+- `footer_actions`: This appears in the right-hand side of the footer.  E.g., numpy.org uses it for mailing list subscriptions.
+
+## Shortcut list
+
+The depths of the shortcut list on the left of each post can be
+controlled by setting the `shortcutDepth` parameter in the post
+preamble.  It defaults to 2.
+
+## Page information
+
+Each page should contain a `summary` in the preamble, otherwise the
+site description is provided as metadata.
+
+## Code styling
+
+To enable code styling, add the following to your config file:
+
+```yaml
+markup:
+  highlight:
+    noClasses: false
+```
+
+The default theme is [Witch Hazel](https://github.com/theacodes/witchhazel),
+but with a blue background.
+To use a different theme, [generate a new
+stylesheet](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode)
+using:
+
+```bash
+hugo gen chromastyles --style=monokai > /assets/css/code-highlight.css
+```
+
+You can replace `monokai` with any of the themes supported by
+[Chroma](https://github.com/alecthomas/chroma), as listed in their
+[gallery](https://xyproto.github.io/splash/docs/).
+
+Then, use fenced code blocks and remember to specify the language:
+
+````md
+```python
+def foo(x):
+    return x**2
+```
+````
+
+## News
+
+The first post from `/content/en/news` will be highlighted on the
+front page.  If you don't want that, remove the `/content/en/news`
+folder.
+
+By default, news items link to the `/news` category page (which lists all news items).
+You can override that by setting `newsLink` in the preamble of any news post.
+
+## Team gallery
+
+The `tools/team_query.py` file gets a list of team members from GitHub.  To
+use it, you will need to set the GH_TOKEN environment variable
+to a personal access token.
+
+The team is rendered using shortcodes (`team`, `team_member`).
+
+Example usage:
+
+```
+python team_query.py --org scientific-python --team spec-steering-committee --title "Spec Steering Committee" > content/en/teams/spec-steering-committee.md
+```
+
+we generate a raw HTML gallery, and provide a
+shortcode (include-html) for pulling it in anywhere on the site.

doc/content/getstarted.md

@@ -13,7 +13,7 @@ To use the theme, you will need to
 [download hugo](https://github.com/gohugoio/hugo/releases)
 and place it on your path.
 
-## Getting started
+## Download and install
 
 1. Download [the theme ZIP file](https://github.com/scientific-python/scientific-python-hugo-theme/archive/refs/heads/main.zip) and extract it.
 2. Copy the `doc` folder as a template of your new website:
@@ -58,72 +58,9 @@ e.g. to access configuration variables as `{{ .Site.Params.somevar }}`.
 
 Add custom JavaScript to `static/js/*.js`.
 
-## Shortcodes
+## Next steps
 
-See [shortcodes]({{< relref "shortcodes" >}}).
-
-## Partials
-
-The following partials are meant to be overridden:
-
-- `post_meta.html`: Render meta-data under a post title.
-                    We have not yet defined this template, but you can use it to add author information, date, etc.
-- `footer_actions`: This appears in the right-hand side of the footer.  E.g., numpy.org uses it for mailing list subscriptions.
-
-## Shortcut list
-
-The depths of the shortcut list on the left of each post can be
-controlled by setting the `shortcutDepth` parameter in the post
-preamble.  It defaults to 2.
-
-## Page information
-
-Each page should contain a `summary` in the preamble, otherwise the
-site description is provided as metadata.
-
-## News
-
-The first post from `/content/en/news` will be highlighted on the
-front page.  If you don't want that, remove the `/content/en/news`
-folder.
-
-By default, news items link to the `/news` category page (which lists all news items).
-You can override that by setting `newsLink` in the preamble of any news post.
-
-## Code styling
-
-To enable code styling, add the following to your config file:
-
-```yaml
-markup:
-  highlight:
-    noClasses: false
-```
-
-The default theme is [Witch
-Hazel](https://github.com/theacodes/witchhazel), but with a blue
-background.  To use a different theme, [generate a new
-stylesheet](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode)
-using:
-
-```bash
-hugo gen chromastyles --style=monokai > /assets/css/code-highlight.css
-```
-
-You can replace `monokai` with any of the themes supported by
-[Chroma](https://github.com/alecthomas/chroma), as listed [in their
-gallery](https://xyproto.github.io/splash/docs/).
-
-Then, use fenced code blocks and remember to specify the language:
-
-````md
-```python
-def foo(x):
-    return x**2
-```
-````
-
-## Example sites
+See [features]({{< relref "features" >}}) and [shortcodes]({{< relref "shortcodes" >}}).
 
 See the
 [scientific-python.org](https://github.com/scientific-python/scientific-python.org),

tools/render_shortcode_docs.py

@@ -33,15 +33,29 @@ def shortcode_doc(fn):
 ---
 title: Shortcodes
 sidebar: true
+shortcutDepth: 1
 ---
+
+<!-- DO NOT EDIT.  This file is generated by `tools/render_shortcode_docs.py`.  -->
+
+Markdown is a convenient and simple format to write in.
+However, it doesn't always do everything we want (or do it in a nice way).
+Rather than adding raw HTML to our source files, Hugo allows us to use
+_shortcodes_.  Shortcodes are small snippets that look like this
+```
+{{</* _shortcodename parameters_ */>}}
+```
+that Hugo renders using a predefined template.
+
+Here are some shortcodes used by this theme.
 ''')
 
 for shortcode_fn in shortcodes:
     title = os.path.basename(shortcode_fn).replace('.html', '')
     description, example, code = shortcode_doc(shortcode_fn)
     if description is None:
         continue
-    print(f"### `{title}`")
+    print(f"## `{title}`")
     print()
     print(description)
     print(f"```\n{example}\n```")