docs: Merge the cppdocs into the slintdocs

This replaces the `slintdocs` and the `cppdocs` xtasks with a `docs` task and merges the C++ doocumentation into the Slint Reference
slint-ui · Oct 17, 2024 · 12ed672 · 12ed672
1 parent 3bc2967
commit 12ed672
Show file tree

Hide file tree

Showing 31 changed files with 248 additions and 399 deletions.
diff --git a/.github/workflows/build_docs.yaml b/.github/workflows/build_docs.yaml
@@ -52,7 +52,7 @@ jobs:
                   sudo apt-get install python3-pip pipenv
             - name: Remove docs from cache # Avoid stale docs
               run: |
-                  rm -rf target/doc target/cppdocs api/node/docs
+                  rm -rf target/doc target/docs api/node/docs
             - name: Check license headers
               run: cargo xtask check_license_headers --fix-it
             - name: Suggest license header changes
@@ -66,13 +66,6 @@ jobs:
               run: cargo xtask check_reuse_compliance
 
             # Build Docs
-            - name: Build Cpp docs
-              run: |
-                CPPDOCS_EXTRA_FLAGS="" 
-                if [ "$RELEASE_INPUT" != "true" ]; then
-                    CPPDOCS_EXTRA_FLAGS="--experimental"
-                fi
-                cargo xtask cppdocs --show-warnings $CPPDOCS_EXTRA_FLAGS
             - name: "Rust docs"
               run: cargo doc -p slint -p slint-build -p slint-interpreter --no-deps --all-features
             - name: "Rust android-activity and i-slint-backend-winit"
@@ -96,7 +89,7 @@ jobs:
                 fi
                 sed -i "s/\$TYPESENSE_SERVER_PORT/443/g" "$searchbox_html"
                 sed -i "s/\$TYPESENSE_SERVER_URL/typesense.slint.dev/g" "$searchbox_html"
-                cargo xtask slintdocs --show-warnings
+                cargo xtask docs --show-warnings
             - name: "Node docs"
 
               run: |
@@ -142,13 +135,12 @@ jobs:
                   name: docs
                   path: |
                       target/doc
-                      target/cppdocs/html
-                      target/slintdocs/html
+                      target/docs/html
                       api/node/docs
                       docs/site
             - name: "Check for docs warnings in internal crates"
               run: cargo doc --workspace --no-deps --all-features --exclude slint-node --exclude pyslint --exclude mcu-board-support --exclude printerdemo_mcu --exclude carousel --exclude test-* --exclude plotter --exclude uefi-demo --exclude ffmpeg --exclude gstreamer-player --exclude slint-cpp --exclude slint-python
             - name: Clean cache # Don't cache docs to avoid them including removed classes being published
               run: |
-                  rm -rf target/doc target/cppdocs target/slintdocs api/node/docs
+                  rm -rf target/doc target/docs api/node/docs
 
diff --git a/.github/workflows/nightly_snapshot.yaml b/.github/workflows/nightly_snapshot.yaml
@@ -347,7 +347,7 @@ jobs:
             - name: Extract Version
               id: version
               run: |
-                version=$(grep -oP '(?<=<p class="title logo__title">Slint )[0-9]+\.[0-9]+\.[0-9]+' target/slintdocs/html/index.html)
+                version=$(grep -oP '(?<=<p class="title logo__title">Slint )[0-9]+\.[0-9]+\.[0-9]+' target/docs/html/index.html)
                 if [[ -z "$version" ]]; then
                   echo "Version not found"
                   exit 1
@@ -424,8 +424,6 @@ jobs:
                 rm -rf $output_path/docs
                 mkdir -p $output_path/docs
                 cp -a ../docs/site/* $output_path/docs
-                mkdir -p $output_path/docs/cpp
-                cp -a ../target/cppdocs/html/* $output_path/docs/cpp/
                 mkdir -p $output_path/docs/rust
                 cp -a ../target/doc/* $output_path/docs/rust/
 
@@ -435,7 +433,7 @@ jobs:
                 mkdir -p $output_path/docs/node
                 cp -a ../api/node/docs/* $output_path/docs/node/
                 mkdir -p $output_path/docs/slint
-                cp -a ../target/slintdocs/html/* $output_path/docs/slint/
+                cp -a ../target/docs/html/* $output_path/docs/slint/
 
             - name: Adjust redirections
               if: github.event.inputs.release == 'true'

diff --git a/api/cpp/docs/Pipfile b/api/cpp/docs/Pipfile
diff --git a/api/cpp/docs/_static/theme_tweak.css b/api/cpp/docs/_static/theme_tweak.css
diff --git a/api/cpp/docs/_templates/base.html b/api/cpp/docs/_templates/base.html
diff --git a/api/cpp/docs/conf.py b/api/cpp/docs/conf.py
diff --git a/api/cpp/docs/mcu/intro.md b/api/cpp/docs/mcu/intro.md
diff --git a/docs/building.md b/docs/building.md
@@ -227,21 +227,25 @@ The Slint documentation consists of five parts:
 
 The quickstart guide is part of the DSL documentation.
 
-### Quickstart and DSL docs
+### Quickstart and Docs
 
-The quickstart and DSL docs are written in markdown and built with Sphinx, using the myst parser extension.
+The quickstart and docs are written in markdown and built with Sphinx, using the myst parser extension.
 
 **Prerequisites**:
 
 - [pipenv](https://pipenv.pypa.io/en/latest/)
-- [Python](https://www.python.org/downloads/)
+- [Python](https://www.python.org/downloads/)A
+- [Sphinx](https://www.sphinx-doc.org/)
+- [Doxygen](https://www.doxygen.nl/download.html)
 
-Use the following command line to build the documentation using `rustdoc` to the `target/slintdocs/html` folder:
+Use the following command line to build the documentation using `sphinx` to the `target/docs/html` folder:
 
 ```shell
-cargo xtask slintdocs --show-warnings
+cargo xtask docs --show-warnings
 ```
 
+This also includes any C++ specific doocumentation.
+
 ### Rust API docs
 
 Run the following command to generate the documentation using rustdoc in the `target/doc/` sub-folder:
@@ -254,15 +258,7 @@ Note: `--html-in-header` arguments passed to rustdoc via `RUSTDOCFLAGS` are used
 
 ### C++ API docs
 
-**Prerequisites**:
-
-- [Doxygen](https://www.doxygen.nl/download.html)
-
-Run the following command to generate the documentation using sphinx/exhale/breathe/doxygen/myst_parser in the `target/cppdocs` sub-folder:
-
-```sh
-cargo xtask cppdocs
-```
+See [Quickstart and Docs].
 
 ### Node.js API docs
 
@@ -324,7 +320,7 @@ The script accepts the following arguments
 
 -c : Location of config file (default: `docs/search/scraper-config.json`)
 
--d : Location of index.html of docs (default: `target/slintdocs/html`)
+-d : Location of index.html of docs (default: `target/docs/html`)
 
 -i : Name of the search index (default: `local`)
 
@@ -351,7 +347,7 @@ docs/search/docsearch-scraper.sh -a API_KEY -b -r TYPESENSE_CLOUD_HOST_NAME
 Run http server
 
 ```sh
-python3 -m http.server -d target/slintdocs/html
+python3 -m http.server -d target/docs/html
 ```
 
 Open browser (<http://localhost:8000>) and use the search bar to search for content
diff --git a/docs/editor/vite.config.ts b/docs/editor/vite.config.ts
@@ -16,6 +16,6 @@ export default defineConfig({
                 "https://snapshots.slint.dev/master/wasm-interpreter/slint_wasm_interpreter.js",
             ],
         },
-        outDir: "../../target/slintdocs/_static",
+        outDir: "../../target/docs/_static",
     },
 });
diff --git a/docs/reference/Pipfile b/docs/reference/Pipfile
@@ -9,16 +9,19 @@ verify_ssl = true
 [dev-packages]
 
 [packages]
-sphinx = "==7.1.2"
+breathe = ">=4.33.1"
+exhale = ">=0.2.4"
+# furo = ">=2022.12.7"
+linkify-it-py = ">=2.0.3"
 myst_parser = ">=2.0.0"
+sphinx = "==7.1.2"
+sphinx-copybutton = ">=0.5.2"
 sphinx-design = ">=0.5.0"
-sphinx-tabs = ">=3.4.5"
 sphinx-markdown-tables = ">=0.0.15"
+sphinx-sitemap = ">=2.6.0"
+sphinx-tabs = ">=3.4.5"
 sphinx_book_theme = ">=1.1.3"
 sphinxcontrib-jquery = ">=4.1"
-sphinx-copybutton = ">=0.5.2"
-linkify-it-py = ">=2.0.3"
-sphinx-sitemap = ">=2.6.0"
 
 [requires]
 python_version = "3"