From 2b65b53f8d50f9c317a8bbee0b1d6231a492c56b Mon Sep 17 00:00:00 2001 From: Jarrod Millman Date: Tue, 9 Nov 2021 12:29:46 -0800 Subject: [PATCH] Reorg docs (#67) * Reorg docs * Feedback form tupui --- doc/config.yaml | 12 +++-- doc/content/features.md | 82 ++++++++++++++++++++++++++++++++++ doc/content/getstarted.md | 69 ++-------------------------- doc/content/shortcodes.md | 6 --- tools/render_shortcode_docs.py | 16 ++++++- 5 files changed, 108 insertions(+), 77 deletions(-) create mode 100644 doc/content/features.md delete mode 100644 doc/content/shortcodes.md diff --git a/doc/config.yaml b/doc/config.yaml index 2426a1b0..0edc1072 100644 --- a/doc/config.yaml +++ b/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: diff --git a/doc/content/features.md b/doc/content/features.md new file mode 100644 index 00000000..f7cab1bf --- /dev/null +++ b/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. diff --git a/doc/content/getstarted.md b/doc/content/getstarted.md index c221728a..39dd5fc5 100644 --- a/doc/content/getstarted.md +++ b/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), diff --git a/doc/content/shortcodes.md b/doc/content/shortcodes.md deleted file mode 100644 index 3f394db5..00000000 --- a/doc/content/shortcodes.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Shortcodes -sidebar: true ---- - -Please run `tools/render_shortcode_docs.py` to generate this file. diff --git a/tools/render_shortcode_docs.py b/tools/render_shortcode_docs.py index 5d425d0d..3ba73e2a 100644 --- a/tools/render_shortcode_docs.py +++ b/tools/render_shortcode_docs.py @@ -33,7 +33,21 @@ def shortcode_doc(fn): --- title: Shortcodes sidebar: true +shortcutDepth: 1 --- + + + +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 +``` +{{}} +``` +that Hugo renders using a predefined template. + +Here are some shortcodes used by this theme. ''') for shortcode_fn in shortcodes: @@ -41,7 +55,7 @@ def shortcode_doc(fn): 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```")