Merge pull request #203 from qgis/docs-and-refactor

Docs and refactor
qgis · Mar 1, 2024 · d76f23f · d76f23f
2 parents 89b5391 + 49823fd
commit d76f23f
Show file tree

Hide file tree

Showing 31 changed files with 200 additions and 63 deletions.
diff --git a/README.md b/README.md
@@ -261,6 +261,25 @@ tricky part: shortcodes can't be used as other shortcodes' params. So you need t
 This table represents required redirects from old URL structure to the new one:
 https://docs.google.com/spreadsheets/d/12Oo761Zwgj4iLeJxdrg8I31rGzsB95z5M1PpW9pYma8/edit?usp=sharing
 
+Notes:
+
+- it will be more convenient to store all redirects in same file (nginx conf or else)
+- hugo aliases not recommended: they work, but don't support regex. also hard to maintain: redirects are spread across content files
+- use regexps to redirect from all langs
+- use regexps to map between similar stuff (case studies, visual changelog) - example rewrite rules below
+
+Bulk redirects can be done like
+
+```
+location ~ ^/[A-Za-z-]+/site/about/case_studies/(.*).html {
+  rewrite ^/[A-Za-z-]+/site/about/case_studies/(.*).html /product/case-studies/$1/ permanent;
+}
+
+location ~ ^/[A-Za-z-]+/site/forusers/visualchangelog(.*)/index.html {
+  rewrite ^/[A-Za-z-]+/site/forusers/visualchangelog(.*)/index.html /product/visual-changelogs/visualchangelog$1/ permanent;
+}
+```
+
 ## Stripe donations
 
 main donation page: [https://qgis.github.io/QGIS-Hugo/funding/donate/](https://qgis.github.io/QGIS-Hugo/funding/donate/)
@@ -275,4 +294,4 @@ Payment options are implemented with [Payment Links](https://docs.stripe.com/no-
 docker run --rm dcycle/broken-link-checker:3 https://qgis.github.io/QGIS-Hugo > broken_links.csv
 ```
 
-Crawls the site and reports all 404
+Crawls the site and reports all 404. Full run takes apout 10 mins
diff --git a/data/conf.json b/data/conf.json
@@ -1,7 +1,8 @@
 {
+    "WARNING": "produced from googlesheet via scripts/update-schedule.py - EDITS WILL BE LOST",
     "version": "3.36",
     "release": "3.36.0",
-    "releasedate": "2024, 2, 23",
+    "releasedate": "23.02.2024",
     "binary": "1",
     "codename": "Maidenhead",
     "releasenote": "RC",
@@ -16,7 +17,7 @@
     "nextfreezedate": "2024-05-17 12:00:00 UTC",
     "nextreleasedate": "2024-06-21 12:00:00 UTC",
     "nextpointreleasedate": "2024-03-22 12:00:00 UTC",
-    "infeaturefreeze": true,
+    "infeaturefreeze": false,
     "yeartag": "%%Y",
     "devcite": "https://docs.qgis.org/3.34/en/docs/developers_guide/index.html",
     "userguidecite": "https://docs.qgis.org/3.34/en/docs/user_manual/index.html",
@@ -27,4 +28,4 @@
     "ltr_msi": "https://qgis.org/downloads/QGIS-OSGeo4W-3.34.4-1.msi",
     "ltr_sha": "https://qgis.org/downloads/QGIS-OSGeo4W-3.34.4-1.sha256sum",
     "weekly_msi": "https://download.osgeo.org/qgis/windows/weekly/?C=M&O=D"
-}
+}
diff --git a/docs/shortcodes/csv-table.md b/docs/shortcodes/csv-table.md
@@ -0,0 +1,29 @@
+## csv-table
+
+Can render a html table from CSV file or inner content
+
+```
+{{< csv-table file="csv/schedule.csv" />}}
+```
+
+![](img/csv-table.png)
+
+Example usage with inner content CSV:
+
+```
+{{< csv-table >}}
+"LTR","Long term release, begin of new development phase"
+"LR","Regular release, begin of new development phase"
+"FF","Feature freeze, end of development phase"
+"PR","Point release of latest release and LTR branch"
+"EPR","Extra Point release"
+":rm-current:current",":rm-current:currently supported releases: {{< param "ltrrelease" >}} and {{< param "release" >}}"
+":rm-next:next",":rm-next:next releases"
+{{< /csv-table >}}
+```
+
+Note: `param` can be used inside to substitute dynamic vars
+
+![](img/csv-table-1.png)
+
+`:rm-next:`, `:rm-current:`, etc. are transformed into CSS classes from themes/hugo-bulma-blocks-theme/assets/sass/bulma/components/roadmap.sass. Currently this shortcode is used only for roadmap tables, that's why it's called roadmap.sass
diff --git a/docs/shortcodes/download-macos.md b/docs/shortcodes/download-macos.md
@@ -0,0 +1,5 @@
+```
+{{< download-macos >}}
+```
+
+Contains links with MacOS installers
diff --git a/docs/shortcodes/download-windows.md b/docs/shortcodes/download-windows.md
@@ -0,0 +1,5 @@
+```
+{{< download-windows >}}
+```
+
+Contains links with Windows installers
diff --git a/docs/shortcodes/img/csv-table-1.png b/docs/shortcodes/img/csv-table-1.png
diff --git a/docs/shortcodes/img/csv-table.png b/docs/shortcodes/img/csv-table.png
diff --git a/docs/shortcodes/img/spoiler.png b/docs/shortcodes/img/spoiler.png
diff --git a/docs/shortcodes/img/stripe-widget-1.png b/docs/shortcodes/img/stripe-widget-1.png
diff --git a/docs/shortcodes/img/stripe-widget.png b/docs/shortcodes/img/stripe-widget.png
diff --git a/docs/shortcodes/img/table-of-contents.png b/docs/shortcodes/img/table-of-contents.png
diff --git a/docs/shortcodes/img/usecase.png b/docs/shortcodes/img/usecase.png
diff --git a/docs/shortcodes/img/usecases.png b/docs/shortcodes/img/usecases.png
diff --git a/docs/shortcodes/mobile-downloads.md b/docs/shortcodes/mobile-downloads.md
@@ -0,0 +1,5 @@
+```
+{{< mobile-downloads >}}
+```
+
+Contains links to mobile app downloads
diff --git a/docs/shortcodes/param-link.md b/docs/shortcodes/param-link.md
@@ -0,0 +1,20 @@
+## `param-link` Shortcode
+
+The `param-link` is different from `param` in a way that it applies `| markdownify` to its content. So the plain-text links will be rendered as clickable `<a>` tags
+
+### Parameters
+
+- `name`: The name of the configuration parameter to retrieve.
+
+### Example Usage
+
+```
+Electronic document: {{< param-link "userguidecite" >}}
+```
+
+^ will be rendered like `Electronic document: [https://docs.qgis.org/3.34/en/docs/developers_guide/index.html](https://docs.qgis.org/3.34/en/docs/developers_guide/index.html)`
+
+### Additional Notes
+Make sure that the parameter you are trying to access exists in the data/conf.json.
+
+Also see notes about automation of LT/LTR variables in the root README
diff --git a/docs/shortcodes/param.md b/docs/shortcodes/param.md
@@ -1,22 +1,23 @@
 ## `param` Shortcode
 
-The `param` shortcode is used to retrieve and display a specific configuration parameter from the site's data files.
+The `param` shortcode is used to retrieve and display a specific parameter from data/conf.json. This file is in sync with QGIS release schedule and contains variables related to roadmap.
 
 ### Parameters
 
 - `name`: The name of the configuration parameter to retrieve.
 
 ### Example Usage
 
-To use the `param` shortcode, you need to pass the name of the configuration parameter as an argument. For example, if you want to retrieve the `email` parameter from the site's configuration:
-
-```html
-{{< param "email" >}}
+```
+the latest stable QGIS ({{< param "version" >}}.x {{< param "codename" >}}) 
 ```
 
-This will output the value of the email parameter from the site's configuration data.
+^ will be rendered as `the latest stable QGIS (3.36.x Maidenhead)`
 
 ### Additional Notes
-The configuration parameters are typically stored in the data directory of your Hugo site, in a file named conf.toml, conf.yaml, or conf.json.
-Make sure that the parameter you are trying to access exists in the site's configuration data files.
-This shortcode is useful for displaying dynamic content that is defined in the site's configuration and needs to be consistent across multiple pages.
+Make sure that the parameter you are trying to access exists in the data/conf.json.
+This shortcode is useful for displaying dynamic content that is defined in the site's configuration and needs to be consistent across multiple pages.
+
+The shortcode is rendered as plain text. To automatically generate a clickeble link, use `param-link`
+
+Also see notes about automation of LT/LTR variables in the root README
diff --git a/docs/shortcodes/paypal-button.md b/docs/shortcodes/paypal-button.md
@@ -0,0 +1,5 @@
+```
+{{< paypal-button >}}
+```
+
+inserts a button that leads to PayPal checkout
diff --git a/docs/shortcodes/script.md b/docs/shortcodes/script.md
@@ -0,0 +1,5 @@
+```
+{{< script src="js/spoiler.js" >}}
+```
+
+Is used to include some javascript into content file. JS files are taken from ./themes/hugo-bulma-blocks-theme/assets/js/spoiler
diff --git a/docs/shortcodes/spoiler.md b/docs/shortcodes/spoiler.md
@@ -0,0 +1,9 @@
+```
+{{< spoiler-start id="download-bsd" title="Download for BSD" >}}
+[BSD Installation Instructions]({{< ref "resources/installation-guide#freebsd" >}})
+{{< spoiler-end >}}
+```
+
+Foldable section. May contain md, html and other shortcodes inside
+
+![](img/spoiler.png)
diff --git a/docs/shortcodes/stripe-widget.html b/docs/shortcodes/stripe-widget.html
@@ -0,0 +1,23 @@
+```
+{{< stripe-widget >}}
+
+or 
+
+{{< stripe-widget otherMethods="true">}}
+```
+
+Inserts a donation form integrated with Stripe. Donate options are controlled by data/stripe_products.yml
+
+![](img/stripe-widget.png)
+
+Used inside `rich-right` block:
+
+```
+{{< rich-right-start >}}
+{{< stripe-widget otherMethods="true">}}
+{{< rich-right-end >}}
+```
+
+`otherMethods="true"` inserts the link to /funding/donate/ page
+
+![](img/stripe-widget-1.png)
diff --git a/docs/shortcodes/table-of-contents.md b/docs/shortcodes/table-of-contents.md
@@ -0,0 +1,7 @@
+```
+{{< table-of-contents >}}
+```
+
+Creates a list with links to anchor-headers from the current page. Currently used in visual changelogs
+
+![](img/table-of-contents.png)
diff --git a/docs/shortcodes/usecase.md b/docs/shortcodes/usecase.md
@@ -1,23 +1,13 @@
-## `usecase` Shortcode
-
-The `usecase` shortcode is designed to create a rich list item that links to a case study. It includes a thumbnail image, a title, and a short description.
-
-### Parameters
-
-- `thumbnail`: The filename of the thumbnail image to display. The image should be located in the `/product/case-studies/` directory.
-- `title`: The title of the case study.
-- `description`: A brief description of the case study.
-
-### Example Usage
+```
+{{< usecase >}}
+```
 
-To use the `usecase` shortcode, you need to pass the `thumbnail`, `title`, and `description` parameters like so:
+Creates a card with the first case study from content/product/case-studies. Currently used within `rich-right` block
 
-```html
-{{< usecase thumbnail="image.jpg" title="Case Study Title" description="A short description of the case study." >}}
 ```
-This will generate a rich list item with an image, title, and description that links to the specified case study.
+{{< rich-right-start >}}  
+{{< usecase >}}
+{{< rich-right-end >}}
+```
 
-### Additional Notes
-Ensure that the thumbnail image exists in the specified directory and is accessible.
-The title and description should be concise and relevant to the content of the case study they link to.
-This shortcode is typically used within a loop to display multiple case studies.
+![](img/usecase.png)
diff --git a/docs/shortcodes/usecases.md b/docs/shortcodes/usecases.md
@@ -0,0 +1,7 @@
+```
+{{< usecases >}}
+```
+
+Creates a grid with images and links to all case studies from content/product/case-studies
+
+![](img/usecases.png)
diff --git a/docs/shortcodes/visualchangelogs.md b/docs/shortcodes/visualchangelogs.md
@@ -0,0 +1,5 @@
+```
+{{< visualchangelogs >}}
+```
+
+Creates a list of Visual Changelogs from content/product/visual-changelogs ordered by release date. Each list item is a link to corresponding changelog page
diff --git a/layouts/funding/section.html b/layouts/funding/section.html
diff --git a/scripts/update-schedule.py b/scripts/update-schedule.py
@@ -1,6 +1,14 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
+'''
+this script should be run from the root repo directory (../)
+
+$ python scripts/update-schedule.py
+
+will update data/conf.json and scripts/schedule.ics
+'''
+
 from urllib.request import urlopen
 import csv
 import json
@@ -210,7 +218,9 @@ def adduid(ev, uid):
 
 shortver = "".join(lr_version.split(".")[:2])
 for f in [
-        # f"themes/qgis-theme/static/images/qgisorg_banner{shortver}.png", # TODO
+        # NOTE: there's no dir for versioned banners for the current website
+        # f"themes/qgis-theme/static/images/qgisorg_banner{shortver}.png", 
+        # TODO: no changelog for 3.36
         # f"content/product/visual-changelogs/visualchangelog{shortver}/index.md"
 ]:
     assert os.path.exists(f), f"{f} not found"
@@ -219,6 +229,7 @@ def adduid(ev, uid):
 
 with open("data/conf.json", "w") as f:
     json.dump({
+        "WARNING": "this json is produced from googlesheet via scripts/update-schedule.py - EDITS WILL BE LOST",
         "version": ".".join(lr_version.split(".")[:2]),
         "release": lr_version,
         "releasedate": lr_date.strftime("%d.%m.%Y"),

diff --git a/layouts/_default/_markup/render-link.html → ...layouts/_default/_markup/render-link.html b/layouts/_default/_markup/render-link.html → ...layouts/_default/_markup/render-link.html
diff --git a/themes/hugo-bulma-blocks-theme/layouts/partials/usecase.html b/themes/hugo-bulma-blocks-theme/layouts/partials/usecase.html
@@ -0,0 +1,6 @@
+<div class="tile">
+    <a class="rich-list has-image mr-2 mb-2" href="{{ .RelPermalink }}" >
+        <div class="image"><img src="{{ absURL "product/case-studies/" }}{{ .Params.thumbnail }}"></div>
+        <div class="listcont ">{{.Title}}</div>
+    </a>
+</div>
diff --git a/themes/hugo-bulma-blocks-theme/layouts/shortcodes/roadmap.html b/themes/hugo-bulma-blocks-theme/layouts/shortcodes/roadmap.html
@@ -216,8 +216,13 @@ <h3 class="title">Development Version</h3>
         var timeinterval = setInterval(updateClock, 1000);
       }
 
-      var deadline = new Date(Date.parse(new Date()) + 15 * 24 * 60 * 60 * 1000);
-      initializeClock('point-release', deadline);
-      initializeClock('freeze', deadline);
-      initializeClock('package', deadline);
-    </script>
+      {{ with index .Site.Data.conf }}
+        const nextFreezeDate = new Date({{ .nextfreezedate }});
+        const nextReleaseDate = new Date({{ .nextreleasedate }});
+        const nextPointReleaseDate = new Date({{ .nextpointreleasedate }});
+      {{ end }}
+
+      initializeClock('point-release', nextPointReleaseDate);
+      initializeClock('freeze', nextFreezeDate);
+      initializeClock('package', nextReleaseDate);
+    </script>
diff --git a/themes/hugo-bulma-blocks-theme/layouts/shortcodes/usecase.html b/themes/hugo-bulma-blocks-theme/layouts/shortcodes/usecase.html
@@ -1,11 +1,5 @@
 {{ range (where .Site.Pages "Section" "product") }}
-{{ range (where .Pages "SectionsPath" "product/case-studies") | first 1 }}
-<a class="rich-list has-image mr-2 mb-2" href="{{ .RelPermalink }}" >
-    <div class="image"><img src="{{ absURL "product/case-studies/" }}{{ .Params.thumbnail }}"></div>
-<div class="listcont ">{{.Title}}</div>
-<div class="subtext is-size-7">{{ .Params.description }}</div>
-</a>
+    {{ range (where .Pages "SectionsPath" "product/case-studies") | first 1 }}
+        {{ partial "usecase.html" . }}
+    {{ end }}
 {{ end }}
-{{ end }}
-
-
diff --git a/themes/hugo-bulma-blocks-theme/layouts/shortcodes/usecases.html b/themes/hugo-bulma-blocks-theme/layouts/shortcodes/usecases.html
@@ -1,13 +1,7 @@
 <div class="grid">
 {{ range (where .Site.Pages "Section" "product") }}
     {{ range (where .Pages "SectionsPath" "product/case-studies") }}
-        <div class="tile">
-            <a class="rich-list has-image mr-2 mb-2" href="{{ .RelPermalink }}" >
-            <div class="image"><img src="{{ .Params.thumbnail }}"></div>
-            <div class="listcont ">{{.Title}}</div>
-            <!--div class="subtext is-size-7">{{ .Params.date }}</div-->
-            </a>
-        </div>
+        {{ partial "usecase.html" . }}
     {{ end }}
 {{ end }}
 </div>