New documentation system

[mathjazz]

Fix #2214.

Please check it out at:
https://pontoon.allizom.org/docs/

[eemeli]

A brief review of the rendered site -- didn't look at the code at all, and ignoring the content completely:

• The "On this page" right-hand column is a bit useless on the four top-level pages, and makes the page feel a bit cramped, esp. as each of those has two-column section links in the main body. Those four pages could instead use a layout that left out that column and used it for main content.
• The highlight colour for search results could be a bit bolder in dark mode.
• The header font width changing when you scroll down is a bit odd, in particular on the front page where the page & site titles are the same.
• The header repo link could use a GitHub logo rather than a generic repo logo, the same as the one in the footer.

[flodolo]

I pushed a commit with a bunch of fixes (content, links).

In general, there's a significant problem: to change something I need to rebuild the whole Docker image. This seems to work locally?

.gitignore requires changes nonetheless.

diff --git a/.gitignore b/.gitignore
index 78f625ecd..ed96f9de5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,8 +19,7 @@ tmp/
 venv/
 
 /docker/config/server.env
-/docs/_build
-/docs/_gh-pages
+/documentation/site/
 /env/
 /media/
 /pontoon/coverage.xml
diff --git a/docker-compose.yml b/docker-compose.yml
index f0731a4bb..a6675d49f 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -18,6 +18,7 @@ services:
       - ./pontoon:/app/pontoon
       - ./requirements:/app/requirements
       - ./translate:/app/translate
+      - ./documentation:/app/documentation
       - ~/.ssh:/home/pontoon/.ssh
 
   # Database
diff --git a/pontoon/urls.py b/pontoon/urls.py
index f95a1675b..3638cffbb 100644
--- a/pontoon/urls.py
+++ b/pontoon/urls.py
@@ -19,9 +19,11 @@ def docs_serve(request, path="index.html"):
     if not path or path.endswith("/"):
         path = f"{path}index.html"
 
-    return serve(
-        request, path, document_root=os.path.join(settings.STATIC_ROOT, "docs")
-    )
+    docs_dir = os.path.join(settings.ROOT, "documentation", "site")
+    if not os.path.isdir(docs_dir):
+        docs_dir = os.path.join(settings.STATIC_ROOT, "docs")
+
+    return serve(request, path, document_root=docs_dir)
 
 
 register_converter(LocaleConverter, "locale")

[flodolo]

Should we just remove this section and link to https://pontoon.allizom.org/docs/admin/adding-new-project/ (instead of linking at the end)?

[mathjazz]

Yeah, that's a good idea.

[mathjazz]

The "On this page" right-hand column is a bit useless on the four top-level pages, and makes the page feel a bit cramped, esp. as each of those has two-column section links in the main body. Those four pages could instead use a layout that left out that column and used it for main content.

Agreed regarding the uselessness of the On this page section on these sites. There's no per-page option to turn that off, but we can hide them with CSS. I'd keep the width of the main content column unchanged - wide content blocks are harder to read.

The highlight colour for search results could be a bit bolder in dark mode.

We use the default color. I'll update to the latest version of the theme, which changed the UI a bit. Let's see if that helps.

The header font width changing when you scroll down is a bit odd, in particular on the front page where the page & site titles are the same.

Agreed. Let's fix that.

The header repo link could use a GitHub logo rather than a generic repo logo, the same as the one in the footer.

That's the default icon and it looks the same on Material for mkdocs, so people might be familiar with.

[flodolo]

We need to update the Help link

pontoon/pontoon/base/templates/header.html

Line 80 in 4bc8ac4

href="https://mozilla-l10n.github.io/localizer-documentation/tools/pontoon/"

[mathjazz]

I pushed a commit with a bunch of fixes (content, links).

Thank you!

In general, there's a significant problem: to change something I need to rebuild the whole Docker image. This seems to work locally?

Yeah, I am aware of this and planning to fix it before we merge. Your approach works. I was trying to avoid having docs in two separate paths (and the need to change urls.py). I'll look into it again.

[mathjazz]

We need to update the Help link

pontoon/pontoon/base/templates/header.html

Line 80 in 4bc8ac4

href="https://mozilla-l10n.github.io/localizer-documentation/tools/pontoon/"

Yup, there's plenty of places that need update like this, already on it.

[flodolo]

I'm going to push a change with updates to docs that landed in
mozilla-l10n/documentation#329
mozilla-l10n/localizer-documentation#295

[codecov-commenter]

Codecov Report

❌ Patch coverage is 50.00000% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.00%. Comparing base (91be114) to head (ec2fb6f).

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[flodolo]

I wonder if it's worth adding a .vscode/settings.json file to exclude some folders from search? It's still not automated, but you can exclude them in one click.

{
  "search.exclude": {
    "**/.git": true,
    "**/node_modules": true,
    "**/documentation/.cache": true
  }
}