Improve versioning of the documentation website and fix page 404 (#3632)

* improve versioning of the documentation website

* fix version dropdown menu

* fix linter errors

* hide contribuiting subsections and update site/build_docs.py

* revert changes contributing section and remove unwanted text

.github/workflows/github_pages.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Build docs
         run: |
-          pip install gitpython packaging
+          pip install gitpython packaging toml
           python site/build_docs.py
 
       - name: Deploy

site/assets/scss/_custom.scss

@@ -133,3 +133,17 @@
 #td-cover-block-0 {
     background-image: url("../images/background-about-page.jpg");
 }
+
+/* Display version menu on mobile version of the site */
+
+#dropdown_ver {
+    right: 5px !important;
+    left: auto;
+}
+
+@media (min-width: 991.98px) {
+    #dropdown_ver {
+        right: 245px !important;
+        left: auto;
+    }
+}

site/build_docs.py

@@ -3,10 +3,12 @@
 # SPDX-License-Identifier: MIT
 
 import os
-from packaging import version
+import shutil
 import subprocess
 
+from packaging import version
 import git
+import toml
 
 MINIMUM_VERSION='1.5.0'
 
@@ -28,10 +30,25 @@ def generate_versioning_config(filename, versions, url_prefix=''):
         file_object.write('url = "{}"\n\n'.format(url))
 
     with open(filename, 'w') as f:
-        write_version_item(f, 'develop', '{}/'.format(url_prefix))
+        write_version_item(f, 'Latest version', '{}/'.format(url_prefix))
         for v in versions:
             write_version_item(f, v, '{}/{}'.format(url_prefix, v))
 
+def git_checkout(tagname, cwd):
+    docs_dir = os.path.join(cwd, 'site', 'content', 'en', 'docs')
+    shutil.rmtree(docs_dir)
+    repo.git.checkout(tagname, '--', 'site/content/en/docs')
+    images_dir = os.path.join(cwd, 'site', 'content', 'en', 'images')
+    shutil.rmtree(images_dir)
+    repo.git.checkout(tagname, '--', 'site/content/en/images')
+
+def change_version_menu_toml(filename, version):
+    data = toml.load(filename)
+    data['params']['version_menu'] = version
+
+    with open(filename,'w') as f:
+        toml.dump(data, f)
+
 def generate_docs(repo, output_dir, tags):
     def run_hugo(content_loc, destination_dir):
         subprocess.run([ # nosec
@@ -50,13 +67,14 @@ def generate_docs(repo, output_dir, tags):
         os.makedirs(output_dir)
 
     generate_versioning_config(os.path.join(cwd, 'site', 'versioning.toml'), (t.name for t in tags))
+    change_version_menu_toml(os.path.join(cwd, 'site', 'versioning.toml'), 'Latest version')
     run_hugo(content_loc, output_dir)
 
     generate_versioning_config(os.path.join(cwd, 'site', 'versioning.toml'), (t.name for t in tags), '/..')
     for tag in tags:
-        repo.git.checkout(tag.name, '--', 'site/content/en/docs')
-        repo.git.checkout(tag.name, '--', 'site/content/en/images')
+        git_checkout(tag.name, cwd)
         destination_dir = os.path.join(output_dir, tag.name)
+        change_version_menu_toml(os.path.join(cwd, 'site', 'versioning.toml'), tag.name)
         os.makedirs(destination_dir)
         run_hugo(content_loc, destination_dir)
 

site/config.toml

@@ -96,7 +96,7 @@ cvat_terms_of_use = "https://cvat.org/api/v1/restrictions/terms-of-use"
 
 # Menu title if your navbar has a versions selector to access old versions of your site.
 # This menu appears only if you have at least one [params.versions] set.
-version_menu = "Releases"
+# version_menu = "Releases"
 
 # Flag used in the "version-banner" partial to decide whether to display a
 # banner on every page indicating that this is an archived version of the docs.

site/content/en/docs/administration/_index.md

@@ -1,9 +1,6 @@
 ---
-
 title: 'Administration'
 linkTitle: 'Administration'
 weight: 3
 description: 'This section contains documents for system administrators.'
-hide_feedback: true
-
 ---

site/content/en/docs/administration/advanced/_index.md

@@ -1,9 +1,6 @@
 ---
-
 title: 'Advanced'
 linkTitle: 'Advanced'
 weight: 2
 description: 'This section contains advanced documents for system administrators.'
-hide_feedback: true
-
 ---

site/content/en/docs/administration/basics/_index.md

@@ -1,9 +1,6 @@
 ---
-
 title: 'Basics'
 linkTitle: 'Basics'
 weight: 1
 description: 'This section contains basic documents for system administrators.'
-hide_feedback: true
-
 ---

site/content/en/docs/contributing/_index.md

@@ -3,8 +3,6 @@ title: 'Contributing to this project'
 linkTitle: 'Contributing'
 weight: 4
 description: 'This section contains documents for CVAT developers.'
-hide_feedback: true
-ul_show: false
 ---
 
 Please take a moment to review this document in order to make the contribution

site/content/en/docs/manual/_index.md

@@ -1,9 +1,6 @@
 ---
-
 title: 'Manual'
 linkTitle: 'Manual'
 weight: 2
 description: 'This section contains documents for CVAT simple and advanced users'
-hide_feedback: true
-
 ---

site/content/en/docs/manual/advanced/_index.md

@@ -3,6 +3,4 @@ title: "Advanced"
 linkTitle: "Advanced"
 weight: 2
 description: 'This section contains advanced documents for CVAT users'
-hide_feedback: true
-
 ---

site/content/en/docs/manual/basics/_index.md

@@ -3,6 +3,4 @@ title: "Basics"
 linkTitle: "Basics"
 weight: 1
 description: 'This section contains basic documents for CVAT users'
-hide_feedback: true
-
 ---

site/content/en/page_404.html

@@ -0,0 +1,11 @@
++++
+Title = 404
++++
+
+  <main id="main">
+    <div class="text-center">
+      <h1>404</h1>
+      <p>Not found</p>
+      <p>Oops! This page doesn't exist. Try going back to our <a href="/about">about page</a> or <a href="/docs">documentation page</a>.</p>
+    </div>
+  </main>

site/i18n/en.toml

@@ -1,23 +1,3 @@
-
-
-# UI strings. Buttons and similar.
-
-[ui_pager_prev]
-other = "Previous"
-
-[ui_pager_next]
-other = "Next"
-
-[ui_read_more]
-other = "Read more"
-
-[ui_search]
-other = "Search this site…"
-
-# Used in sentences such as "Posted in News"
-[ui_in]
-other = "in"
-
 # Footer text
 [footer_intel_privacy_notice]
 other = "Privacy Policy"
@@ -33,31 +13,3 @@ other = "Notices and Disclaimers"
 
 [footer_human_rights_principles]
 other = "Human Rights Principles"
-
-# Post (blog, articles etc.)
-[post_byline_by]
-other = "By"
-[post_created]
-other = "Created"
-[post_last_mod]
-other = "Last modified"
-[post_edit_this]
-other = "Edit this page"
-[post_create_child_page]
-other = "Create child page"
-[post_create_issue]
-other = "Create documentation issue"
-[post_create_project_issue]
-other = "Create project issue"
-[post_posts_in]
-other = "Posts in"
-
-# Print support
-[print_printable_section]
-other = "This the multi-page printable view of this section."
-[print_click_to_print]
-other = "Click here to print"
-[print_show_regular]
-other = "Return to the regular view of this page"
-[print_entire_section]
-other = "Print entire section"

site/layouts/404.html

@@ -1,9 +1 @@
-{{ define "main"}}
-  <main id="main">
-    <div class="text-center">
-      <h1>404</h1>
-      <p>Not found</p>
-      <p>Oops! This page doesn't exist. Try going back to our <a href="./about">about page</a> or <a href="./docs">documentation page</a>.</p>
-    </div>
-  </main>
-{{ end }}
+<meta http-equiv="refresh" content="0; URL=/cvat/page_404">

site/layouts/partials/navbar-version-selector.html

@@ -1,11 +0,0 @@
-{{ $page_rel := .Page.RelPermalink | safeURL }}
-{{ $page_rel_trim := strings.TrimLeft "/" $page_rel | safeURL }}
-<a class="nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
-  {{ .Site.Params.version_menu }}
-</a>
-<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
-  {{ range .Site.Params.versions }}
-    {{ $ver := .version }}
-      <a class="dropdown-item" href="{{ .url }}{{ if eq $ver "develop" }}{{ $page_rel_trim }}{{ else }}{{ $page_rel }}{{ end }}">{{ $ver }}</a>
-  {{ end }}
-</div>

site/layouts/partials/navbar.html

@@ -1,4 +1,6 @@
 {{ $cover := .HasShortcode "blocks/cover" }}
+{{ $page_rel := .Page.RelPermalink | safeURL }}
+{{ $page_rel_trim := strings.TrimLeft "/" $page_rel | safeURL }}
 <nav class="js-navbar-scroll navbar navbar-expand navbar-dark {{ if $cover}} td-navbar-cover {{ end }}flex-column flex-md-row td-navbar">
         <a class="navbar-brand" href="{{ .Site.Home.RelPermalink }}about/">
     <span class="navbar-logo">{{ if .Site.Params.ui.navbar_logo }}{{ with resources.Get "icons/logo.svg" }}{{ ( . | minify).Content | safeHTML }}{{ end }}{{ end }}</span>
@@ -20,9 +22,13 @@
       </li>
       {{ end }}
       {{ if  .Site.Params.versions }}
-      <li class="nav-item dropdown d-none d-lg-block">
-        {{ partial "navbar-version-selector.html" . }}
-      </li>
+        {{ if eq .Page.Type "docs" }}
+        <li class="nav-item dropdown">
+          <a class="nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-target="#dropdown_ver" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+            {{ .Site.Params.version_menu }}
+          </a>
+        </li>
+        {{ end }}
       {{ end }}
       {{ if  (gt (len .Site.Home.Translations) 0) }}
       <li class="nav-item dropdown d-none d-lg-block">
@@ -31,5 +37,11 @@
       {{ end }}
     </ul>
   </div>
+  <div class="dropdown-menu" id="dropdown_ver" aria-labelledby="navbarDropdownMenuLink">
+    {{ range .Site.Params.versions }}
+      {{ $ver := .version }}
+        <a class="dropdown-item" href="{{ .url }}{{ if eq $ver "Latest version" }}{{ $page_rel_trim }}{{ else }}{{ $page_rel }}{{ end }}">{{ $ver }}</a>
+    {{ end }}
+  </div>
   <div class="navbar-nav d-none d-lg-block">{{ partial "search-input.html" . }}</div>
 </nav>