diff --git a/.github/workflows/build_docs.yaml b/.github/workflows/build_docs.yaml index 0bd9222da66..a07a64b6476 100644 --- a/.github/workflows/build_docs.yaml +++ b/.github/workflows/build_docs.yaml @@ -39,23 +39,12 @@ jobs: - uses: actions/setup-node@v4 with: node-version: 20 - - name: Cache mdbook and mdbook-linkcheck - uses: actions/cache@v4 - with: - path: | - ~/.cargo/bin/mdbook - ~/.cargo/bin/mdbook-linkcheck - key: ${{ runner.os }}-${{ github.job }}-mdbook - uses: ./.github/actions/install-linux-dependencies - uses: ./.github/actions/setup-rust with: toolchain: nightly components: rustfmt target: aarch64-linux-android - - name: Install mdbook - run: cargo install mdbook || true - - name: Install mdbook-linkcheck - run: cargo install mdbook-linkcheck || true - name: Install apt dependencies run: sudo apt-get install doxygen - name: Upgrade pip and install pipenv diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index dba9b81ec63..00000000000 --- a/docs/README.md +++ /dev/null @@ -1,119 +0,0 @@ - - -# Tutorials - -The source code for the Rust, C++, and Node.js versions of the Memory Game tutorial are located in -the respect rust, cpp, and node sub-directories. They are built using `mdbook`. - -# Requirements - -Building the tutorial requires `mdbook`, which you can install with `cargo`: - -```sh -cargo install mdbook -``` - -# Building - -Refer to [building.md](./building.md#Generating-the-Documentation) for detailed instructions. - -To build the tutorial, enter the `rust`, `cpp`, or `node` sub-directory and run: - -```sh -mdbook build -``` - -The output will be in the `book/html` subdirectory. To check it out, open it in your web browser. - -# Code Samples - -The code in the tutorial is available in separate steps in .rs, .cpp, and .js files. - -The .rs files are mapped to different binaries, so you if you change into the `rust/src` -sub-directory, then `cargo run` will present you with binaries for the different steps. - -The .cpp files are built using `cpp/src/CMakeLists.txt`, which is included from the top-level -`CMakeLists.txt`. - -# Building search database - -We use Typesense for document search. - -## Infrastructure - -* Typesense Server: The Typesense Server will hold the search index. -* Accessibility: The Typesense server must be accessible from the search bar in documentation site. -* Docker: Docker is needed to run the Typesense Docsearch Scraper. -* Typesense Docsearch Scraper: This tool will be used to index the documentation website. - -## Pre-requisites - -* Install docker () - -* Install jq - -```sh -pip3 install jq -``` - -## Testing Locally - -* Install and start Typesense server () - * Note down the API key, the default port, and the data directory. - -* Verify that the server is running - * Replace the port below with the default port - * It should return {"ok":true} if the server is running correctly. - -```sh -curl http://localhost:8108/health -``` - -## Testing on Typesense Cloud - -* Create an account as per instructions () - * Note down the API key and the hostname. - -## Creating search index - -A helper script is located under `search` sub-folder that will (optionally) build the docs (currently only Slint docs), scrape the documents, and upload the search index to Typesense server. - -The script accepts the following arguments - --a : API key to authenticate with Typesense Server (default: `xyz`) - --b : Build Slint docs (for testing locally set this flag ) (default: `false`) - --c : Location of config file (default: `docs/search/scraper-config.json`) - --d : Location of index.html of docs (default: `target/slintdocs/html`) - --i : Name of the search index (default: `local`) - --p : Port to access Typesense server (default: `8108`) - --r : Remote Server when using Typesense Cloud - --u : URL on which the docs will be served (default: `http://localhost:8000`) - -Example when running locally - -```sh -docs/search/docsearch-scraper.sh -b -``` - -Example when running on Typesense Cloud, where `$cluster_name` is the name of the cluster on Typesense Cloud - -```sh -docs/search/docsearch-scraper.sh -a API_KEY -b -r TYPESENSE_CLOUD_HOST_NAME -``` - -## Testing search functionality - -Run http server - -```sh -python3 -m http.server -d target/slintdocs/html -``` - -Open browser () and use the search bar to search for content diff --git a/docs/building.md b/docs/building.md index 22037912f14..f4ed03fe24a 100644 --- a/docs/building.md +++ b/docs/building.md @@ -276,3 +276,86 @@ Run the following commands from the `/api/node` sub-folder to generate the docs npm install npm run docs ``` + +### Building search database + +We use Typesense for document search. + +#### Infrastructure + +* Typesense Server: The Typesense Server will hold the search index. +* Accessibility: The Typesense server must be accessible from the search bar in documentation site. +* Docker: Docker is needed to run the Typesense Docsearch Scraper. +* Typesense Docsearch Scraper: This tool will be used to index the documentation website. + +#### Pre-requisites + +* Install docker () + +* Install jq + +```sh +pip3 install jq +``` + +#### Testing Locally + +* Install and start Typesense server () + * Note down the API key, the default port, and the data directory. + +* Verify that the server is running + * Replace the port below with the default port + * It should return {"ok":true} if the server is running correctly. + +```sh +curl http://localhost:8108/health +``` + +#### Testing on Typesense Cloud + +* Create an account as per instructions () + * Note down the API key and the hostname. + +#### Creating search index + +A helper script is located under `search` sub-folder that will (optionally) build the docs (currently only Slint docs), scrape the documents, and upload the search index to Typesense server. + +The script accepts the following arguments + +-a : API key to authenticate with Typesense Server (default: `xyz`) + +-b : Build Slint docs (for testing locally set this flag ) (default: `false`) + +-c : Location of config file (default: `docs/search/scraper-config.json`) + +-d : Location of index.html of docs (default: `target/slintdocs/html`) + +-i : Name of the search index (default: `local`) + +-p : Port to access Typesense server (default: `8108`) + +-r : Remote Server when using Typesense Cloud + +-u : URL on which the docs will be served (default: `http://localhost:8000`) + +Example when running locally + +```sh +docs/search/docsearch-scraper.sh -b +``` + +Example when running on Typesense Cloud, where `$cluster_name` is the name of the cluster on Typesense Cloud + +```sh +docs/search/docsearch-scraper.sh -a API_KEY -b -r TYPESENSE_CLOUD_HOST_NAME +``` + +#### Testing search functionality + +Run http server + +```sh +python3 -m http.server -d target/slintdocs/html +``` + +Open browser () and use the search bar to search for content