feat(docussaurus): upgrade Docussaurus and document development procedures #11

see7e · 2025-03-22T15:54:17Z

Changes Summary

This PR refers to #9.
The first commit was a cherry-pick from the same commit (03377f6) made by Conrado. The other changes are listed below.

Removed

No need for docusaurus/blog/ as discussed in Slack, and as the existing text is not relevant to the project, it has been removed.
Removed docusaurus/README.md as it is already present information duplicated with another files like docs/howtos/documentation_development.md.
Removed docusaurus/package-lock.json as the local development should be done with yarn.
Removed unused static files.
Remove HomepageFeatures components as was only being imported and not used.

Added

Added docusaurus/docs/howtos/documentation_development.md as to give instructions on how to develop documentation.
Added docusaurus/docker.package.json to include the dependencies needed to build the containers.

Updated

Improved docusaurus/.dockerignore refenrencing the the other JS modules that are not needed when building the container.
Updated docusaurus/package.json to include the latest versions of the dependencies.
Included at docusaurus/Dockerfile the the new instructions to build the containers of Development and Production.
Improved index.js to include the new components and remove the unused ones.

Test Plan

Basic Docusaurus build tests

Additional Information

This change is backwards-breaking

Security Considerations

Meeting scheduled to 27/03/2025.

lucaaamaral

The only thing I see necessary to restore the removed copyright and remove the CHANGELOG. Everything else seems ok.

CHANGELOG.md

NOTES.md

docusaurus/.gitignore

docusaurus/Dockerfile

docusaurus/docker-compose.yml

docusaurus/docusaurus.config.js

Changing the docusaurus version from costum to the standart open source release Signed-off-by: conradogobato <conradogob07@gmail.com>

…updating dependencies and configurations Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>

…mepage layout and styles Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>

Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>

Remove CHANGELOG and NOTES files, clean up Dockerfile and docker-compose, and update docusaurus configuration Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>

see7e · 2025-03-28T17:33:06Z

Commenting just another task to be done in this PR: need to check the new configuration of docusaurus for the "current" version docs (probably readmes will have to be renamed)

lucaaamaral · 2025-04-02T23:03:30Z

docusaurus/docusaurus.config.js

-          // Please change this to your repo.
-          // Remove this to remove the "edit this page" links.
-          editUrl:
-            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',


Could we have this 'edit this page' pointing to this repository?

lucaaamaral · 2025-04-02T23:06:00Z

Let's bring CI here to be able to merge. I saw you have them done already.

* chore: enhance CI workflows with new scripts for documentation checks and remove obsolete reference check Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * chore: update documentation CI workflow for improved checks and formatting Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * debug: Run everything for testing Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * testing: path filter step dependency removal Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * fix: grant execute permissions to workflow scripts for consistency checks Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * fix: update workflow scripts for improved debugging and path handling Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * fix: Convert format to standad POSIX and streamline with dos2unix dependency and consolidating permission grants Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> * fix: Update workflow scripts to change directory for dependency installation and improve script execution consistency Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com> --------- Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>

see7e · 2025-04-03T17:10:25Z

Let's bring CI here to be able to merge. I saw you have them done already.

Done

lucaaamaral · 2025-04-03T17:56:16Z

.github/workflows/config/markdown_link_check_config.json

Rename to markdown_lint.json. Lint is a check, and it is on configdirectory.

lucaaamaral · 2025-04-03T19:10:30Z

.github/workflows/docs-test.yml

+
+      - name: Run Docusaurus test
+        id: build
+        run: yarn test > build.log 2>&1 || echo "FAILED" > .docusaurus_failed


Remove > build.log 2>&1 || echo "FAILED" > .docusaurus_failed

lucaaamaral · 2025-04-03T19:11:31Z

.github/workflows/docs-test.yml

+      - name: Upload build log
+        uses: actions/upload-artifact@v4
+        with:
+          name: docusaurus-build-log
+          path: build.log
+
+      - name: Save failure flag
+        if: failure()
+        run: echo "Docusaurus build failed"
+


lucaaamaral · 2025-04-03T19:16:39Z

.github/workflows/docs-test.yml

+  translation-consistency:
+    name: Translation Consistency Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install dos2unix dependency
+        run: sudo apt-get update && sudo apt-get install -y dos2unix
+      - name: Grant execute permissions and convert script file
+        run: |
+          chmod +x ./.github/workflows/scripts/check_translations.sh
+          dos2unix ./.github/workflows/scripts/check_translations.sh
+      - name: Check Translation Consistency
+        run: |
+          ./.github/workflows/scripts/check_translations.sh --debug
+        shell: bash


Fix line termination character and remove dos2unix

lucaaamaral · 2025-04-03T19:18:02Z

.github/workflows/docs-test.yml

+  id-filename-sync:
+    name: Docusaurus ID & Filename Sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dos2unix dependency
+        run: sudo apt-get update && sudo apt-get install -y dos2unix
+      - name: Grant execute permissions to scripts and convert script file
+        run: |
+          chmod +x ./.github/workflows/scripts/check_id_matches_filename.sh
+          dos2unix ./.github/workflows/scripts/check_id_matches_filename.sh
+      - name: Check ID matches filename
+        run: |
+          ./.github/workflows/scripts/check_id_matches_filename.sh --debug


Fix line termination character and remove dos2unix

lucaaamaral · 2025-04-03T19:22:04Z

.github/workflows/scripts/check_id_matches_filename.sh

+        *)
+            shift
+            ;;


Throw error if not found

lucaaamaral · 2025-04-03T20:00:27Z

.github/workflows/scripts/check_translations.sh

+    cd docusaurus/docs
+    MODIFIED_DOCS=$(find . -type f \( -name "*.md" -o -name "*.mdx" \) ! -path "versioned_docs/*")
+else
+    BASE_REF="${GITHUB_BASE_REF:-origin/main}"


Set the variables that may be changed based on input at the beginning of the script so it is easy to spot and understand.

lucaaamaral · 2025-04-03T20:05:01Z

.github/workflows/scripts/check_translations.sh

+        continue
+    fi
+
+    REL_PATH=$(echo "$file" | sed 's|^docs/||')


If the purpose is to concatenate, you might just want to make REL_PATH=docs/$file

lucaaamaral · 2025-04-03T20:10:18Z

.github/workflows/scripts/check_id_matches_filename.sh

+    fi
+
+    if [ -n "$found_id" ] && [ "$found_id" != "$expected_id" ]; then
+        rel_path=$(echo "$file" | sed "s|^$DOCS_DIR/||")


Try to keep variable naming convention as all upper case. Also, if you want to concatenate, just make REL_PATH=$DOCS_DIR/$FILE

lucaaamaral · 2025-04-03T20:10:33Z

.github/workflows/scripts/check_id_matches_filename.sh

+    found_id=$(grep -E '^id: ' "$file" | head -n 1 | cut -d ' ' -f2-)
+
+    if [ "$DEBUG_MODE" = "true" ]; then
+        rel_path=$(echo "$file" | sed "s|^$DOCS_DIR/||")


Try to keep variable naming convention as all upper case. Also, if you want to concatenate, just make REL_PATH=$DOCS_DIR/$FILE

lucaaamaral · 2025-04-03T20:12:47Z

.github/workflows/scripts/check_id_matches_filename.sh

+    CHECKED_FILES=$((CHECKED_FILES + 1))
+
+    filename=$(basename "$file")
+    expected_id=$(echo "$filename" | sed 's/\.[^.]*$//')  # Remove extension


You can use that to remove the extention: expected_id=$(basename "$file" .txt)

https://stackoverflow.com/questions/3362920/get-just-the-filename-from-a-path-in-a-bash-script

lucaaamaral requested changes Mar 23, 2025

View reviewed changes

lucaaamaral changed the title ~~Chore: Review configurations, static files and folder structure~~ feat(docussaurus): upgrade Docussaurus and document development procedures Mar 23, 2025

lucaaamaral linked an issue Mar 23, 2025 that may be closed by this pull request

chore: evaluate and port Conrado's PR #9

Open

see7e requested a review from lucaaamaral March 24, 2025 18:37

see7e added 5 commits March 25, 2025 11:01

docs(docusaurus): updated docusaurus

86f3271

Changing the docusaurus version from costum to the standart open source release Signed-off-by: conradogobato <conradogob07@gmail.com>

chore: clean up Docusaurus project by removing unused blog files and …

1c168b7

…updating dependencies and configurations Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>

chore: remove unused images and HomepageFeatures component, update ho…

233c764

…mepage layout and styles Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>

chore: Add last commit updates on CHANGELOG

f6d69a4

Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>

chore: Attend to PR review

5635f10

Remove CHANGELOG and NOTES files, clean up Dockerfile and docker-compose, and update docusaurus configuration Signed-off-by: Gabryel Nóbrega <gabryelster@gmail.com>

lucaaamaral force-pushed the chore/evaluate-conrado-pr branch from 670f346 to 5635f10 Compare March 25, 2025 14:01

lucaaamaral reviewed Apr 2, 2025

View reviewed changes

Merge branch 'main' into chore/evaluate-conrado-pr

1f3023c

lucaaamaral approved these changes Apr 2, 2025

View reviewed changes

lucaaamaral requested changes Apr 3, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docussaurus): upgrade Docussaurus and document development procedures #11

feat(docussaurus): upgrade Docussaurus and document development procedures #11

see7e commented Mar 22, 2025 •

edited

Loading

lucaaamaral left a comment

see7e commented Mar 28, 2025

lucaaamaral Apr 2, 2025

lucaaamaral commented Apr 2, 2025

see7e commented Apr 3, 2025

lucaaamaral Apr 3, 2025

lucaaamaral Apr 3, 2025

lucaaamaral Apr 3, 2025

lucaaamaral Apr 3, 2025

lucaaamaral Apr 3, 2025

lucaaamaral Apr 3, 2025

lucaaamaral Apr 3, 2025

lucaaamaral Apr 3, 2025

lucaaamaral Apr 3, 2025

lucaaamaral Apr 3, 2025

lucaaamaral Apr 3, 2025

feat(docussaurus): upgrade Docussaurus and document development procedures #11

Are you sure you want to change the base?

feat(docussaurus): upgrade Docussaurus and document development procedures #11

Conversation

see7e commented Mar 22, 2025 • edited Loading

Changes Summary

Removed

Added

Updated

Test Plan

Additional Information

Security Considerations

lucaaamaral left a comment

Choose a reason for hiding this comment

see7e commented Mar 28, 2025

Choose a reason for hiding this comment

lucaaamaral commented Apr 2, 2025

see7e commented Apr 3, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

see7e commented Mar 22, 2025 •

edited

Loading