Update hugo/docsy version (cvat-ai#6791)

Newer hugo/docsy versions will allow to use several new features, such as tab groups and tags. - Updated Docsy to v0.7.1 - Updated Hugo to v0.110.0 - Fixed broken layout in the footer - Removed unnecessary breadcrumbs on the main page - Fixed some links in the footer - Updated the build pipeline to build both old and new releases correctly - Added VS Code tasks for docs build steps
amjadsaadeh · Dec 14, 2023 · 8e5f20e · 8e5f20e
1 parent 17894cb
commit 8e5f20e
Show file tree

Hide file tree

Showing 14 changed files with 3,027 additions and 216 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -398,15 +398,21 @@ jobs:
           path: /tmp/cvat_sdk/
 
       - name: Setup Hugo
-        uses: peaceiris/actions-hugo@v2
-        with:
-          hugo-version: '0.83.1'
-          extended: true
+        run: |
+          wget https://github.com/gohugoio/hugo/releases/download/v0.110.0/hugo_extended_0.110.0_Linux-64bit.tar.gz
+          (mkdir hugo_extended_0.110.0_Linux-64bit && tar -xf hugo_extended_0.110.0_Linux-64bit.tar.gz -C hugo_extended_0.110.0_Linux-64bit)
+
+          wget https://github.com/gohugoio/hugo/releases/download/v0.83.0/hugo_extended_0.83.0_Linux-64bit.tar.gz
+          (mkdir hugo_extended_0.83.0_Linux-64bit && tar -xf hugo_extended_0.83.0_Linux-64bit.tar.gz -C hugo_extended_0.83.0_Linux-64bit)
+
+          mkdir hugo
+          cp hugo_extended_0.110.0_Linux-64bit/hugo hugo/hugo-0.110
+          cp hugo_extended_0.83.0_Linux-64bit/hugo hugo/hugo-0.83
 
       - name: Setup Node
         uses: actions/setup-node@v3
         with:
-          node-version: '16.x'
+          node-version: '18.x'
 
       - name: Install npm packages
         working-directory: ./site
@@ -417,7 +423,7 @@ jobs:
         run: |
           pip install -r site/requirements.txt
           python site/process_sdk_docs.py --input-dir /tmp/cvat_sdk/docs/ --site-root site/
-          python site/build_docs.py
+          PATH="$PWD/hugo:$PATH" python site/build_docs.py
         env:
           HUGO_ENV: production
 

diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -455,7 +455,7 @@
             "console": "integratedTerminal"
         },
         {
-            "name": "sdk docs: Postprocess generated docs",
+            "name": "docs: Postprocess SDK docs",
             "type": "python",
             "request": "launch",
             "justMyCode": false,
@@ -469,6 +469,17 @@
             "cwd": "${workspaceFolder}",
             "console": "integratedTerminal"
         },
+        {
+            "name": "docs: Build docs",
+            "type": "python",
+            "request": "launch",
+            "justMyCode": false,
+            "stopOnEntry": false,
+            "python": "${command:python.interpreterPath}",
+            "program": "${workspaceFolder}/site/build_docs.py",
+            "cwd": "${workspaceFolder}",
+            "console": "integratedTerminal"
+        },
         {
             "name": "server: Generate REST API Schema",
             "type": "python",

diff --git a/site/README.md b/site/README.md
@@ -1,6 +1,6 @@
-## Basic manual for website editing
+## Basic manual
 
-### Edit or add documentation pages
+### How to edit or add documentation pages online
 
 To edit and/or add documentation, you need to have a [GitHub](https://github.com/login) account.
 To change documentation files or add a documentation page,
@@ -15,65 +15,129 @@ Read how to edit files for github ([GitHub docs](https://docs.github.com/en/gith
 Please note that files have a markup for correct display on the site: the title, the title of the link,
 the weight (affects the order of files display on the sidebar) and description (optional):
 
-    ---
-    title: "Title"
-    linkTitle: "Link Title"
-    weight: 1
-    description: >
-        Description
-    ---
+```
+---
+title: "Title"
+linkTitle: "Link Title"
+weight: 1
+description: >
+    Description
+---
+```
 
-### Start site localy
 
-To start the site locally, you need a recent [extended version hugo](https://github.com/gohugoio/hugo/releases)
-(recommend version 0.83.1).
-Open the most recent release and scroll down until you find a list of Extended versions. [Read more](https://gohugo.io/getting-started/installing/#quick-install)
+### How to start the site locally
 
-Add a path to "hugo" in the "Path" environment variable.
+#### Installation
 
-Clone a repository branch containing the site. For example, using a git command:
+1. Install Hugo
 
-    git clone --branch <branchname> <remote-repo-url>
+Get the [v110.0-extended release of hugo](https://github.com/gohugoio/hugo/releases/tag/v0.110.0).
+Expand the Assets section of the release on GitHub and and scroll down
+until you find a list of **Extended** versions.
+[Read more](https://gohugo.io/getting-started/installing/#quick-install)
 
-If you want to build and/or serve your site locally, you also need to get local copies of the theme’s own submodules:
+Add a path to `hugo` in the `PATH` environment variable.
 
-    git submodule update --init --recursive
+2. Get the Docsy theme code
 
-To build and preview your site locally, use:
+```bash
+git submodule update --init --recursive
+```
 
-    cd <your local directory>/cvat/site/
-    hugo server
+3. Install the Docsy theme dependencies
+
+To build or update your site’s CSS resources, you will need several packages installed.
+To install them, you must have a recent version of [NodeJS](https://nodejs.org/en/)
+installed on your machine (tested with v18.0). For this, you can use
+[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) directly
+or via an environment manager like [nvm](https://github.com/nvm-sh/nvm).
+By default `npm` installs tools under the directory where you run `npm install`.
+
+```bash
+(cd site/ && npm ci)
+```
+
+The full documentation is available
+[here](https://www.docsy.dev/docs/get-started/other-options/#for-an-existing-site).
+
+4. To preview your site locally, use:
+
+```bash
+(cd site/ && hugo server)
+```
 
 By default, your site will be available at <http://localhost:1313/docs/>.
 
-Instead of a "hugo server" command, you can use the "hugo" command that generates the site into a "public" folder.
+#### How to build for production deployment
+
+1. Install dependencies
+
+```bash
+cd site/
+pip -m venv venv
+. venv/bin/activate
+pip install -r requirements.txt
+```
 
-To build or update your site’s CSS resources you will need [PostCSS](https://postcss.org/) to create final assets.
-To install it you must have a recent version of [NodeJS](https://nodejs.org/en/) installed on your machine,
-so you can use npm, the Node package manager.
-By default npm installs tools under the directory where you run [npm install](https://docs.npmjs.com/cli/v6/commands/npm-install#description):
+The documentation site includes both old and new releases. Because of this,
+you will need tooling for all these releases. Currently, it means you need
+in your environment:
+- `hugo-0.110` - for new docs
+- `hugo-0.83` - for older docs
 
-    cd <your local directory>/cvat/site/
-    npm ci
+Please download these hugo releases (both extended), and make such binaries
+available in your `PATH` environment variable.
 
-Then you can build a website in the "public" folder:
+On Linux, you can install it this way:
 
-    hugo
+```bash
+wget https://github.com/gohugoio/hugo/releases/download/v0.110.0/hugo_extended_0.110.0_Linux-64bit.tar.gz
+(mkdir hugo_extended_0.110.0_Linux-64bit && tar -xf hugo_extended_0.110.0_Linux-64bit.tar.gz -C hugo_extended_0.110.0_Linux-64bit)
+cd hugo_extended_0.110.0_Linux-64bit
+sudo cp hugo /usr/local/bin/hugo-0.110
 
-[Read more](https://www.docsy.dev/docs/getting-started/)
+wget https://github.com/gohugoio/hugo/releases/download/v0.83.0/hugo_extended_0.83.0_Linux-64bit.tar.gz
+(mkdir hugo_extended_0.83.0_Linux-64bit && tar -xf hugo_extended_0.83.0_Linux-64bit.tar.gz -C hugo_extended_0.83.0_Linux-64bit)
+cd hugo_extended_0.83.0_Linux-64bit
+sudo cp hugo /usr/local/bin/hugo-0.83
+```
 
-### Update the submodule of the docsy theme
+2. Use the commands that generate a static site in the `public/` folder:
 
-To update the submodule of the docsy theme you need to have a repository clone. While in the repository folder,
-use the git command:
+Make sure to generate the SDK code first.
 
-    git submodule update --remote
+```bash
+python process_sdk_docs.py --input-dir ../cvat-sdk/docs/ --site-root .
+
+python build_docs.py
+```
+
+The resulting folder contains the whole site, which can be published by a server like Apache.
+Read more [here](https://www.docsy.dev/docs/getting-started/)
+and [here](https://gohugo.io/hosting-and-deployment/).
+
+### How to update the submodule of the Docsy theme
+
+To update the submodule of the docsy theme, you need to have a repository clone.
+While in the repository folder, use the git command:
+
+```bash
+git submodule update --remote
+```
 
 Add and then commit the change to project:
 
-    git add themes/
-    git commit -m "Updating theme submodule"
+```bash
+git add themes/
+git commit -m "Updating theme submodule"
+```
 
 Push the commit to project repo. For example, run:
 
-    git push
+```bash
+git push
+```
+
+Make sure to update the corresponding configuration files and
+theme overrides (`layouts/`, `i18n/`, etc.).
diff --git a/site/assets/scss/_custom.scss b/site/assets/scss/_custom.scss
@@ -2,6 +2,9 @@
 //
 // SPDX-License-Identifier: MIT
 
+/* doesn't work in hugo */
+/* stylelint-disable media-feature-range-notation */
+
 /* Code blocks */
 
 div.code-toolbar .toolbar {
@@ -42,7 +45,7 @@ details > .code-toolbar {
 }
 
 /* Increased left padding on the sidebar of documentation */
-
+/* stylelint-disable-next-line selector-class-pattern */
 .td-sidebar-nav__section .ul-1 ul {
     padding-left: 0.6rem !important;
     padding-right: 0.1rem !important;
@@ -168,15 +171,22 @@ details > .code-toolbar {
 }
 
 /* Display version menu on mobile version of the site */
-
+/* stylelint-disable-next-line selector-id-pattern */
 #dropdown_ver {
     right: 5px !important;
     left: auto;
 }
 
 @media (min-width: 991.98px) {
+    /* stylelint-disable-next-line selector-id-pattern */
     #dropdown_ver {
         right: 245px !important;
         left: auto;
     }
 }
+
+/* Hide breadcrumbs, when on the root level
+   https://github.com/google/docsy/issues/944
+*/
+/* stylelint-disable-next-line selector-class-pattern */
+.td-breadcrumbs__single { display: none !important; }