diff --git a/apps/docs/DEPLOYMENT.md b/apps/docs/DEPLOYMENT.md index c310ffd5..63e9f82e 100644 --- a/apps/docs/DEPLOYMENT.md +++ b/apps/docs/DEPLOYMENT.md @@ -1,10 +1,7 @@ # Deploying the Documentation Site ## Environment Variables -- `PROJECT_ROOT`: The root directory of the project. -- `BUILD_REPO`: The Git repository URL for the documentation site. -- `PRODUCT_VERSION`: The version of the product being documented. -- `BUILD_LATEST`: A boolean flag indicating whether to build the `latest` version. +See [`scripts/README.md`](./scripts/README.md) for the environment variables `deploy.sh` reads (including `DEPLOY_MODE` for staging). ## Overview @@ -13,18 +10,18 @@ set -e source .env ``` -First, we need to build the documentation site via `$PROJECT_ROOT/generate.sh`. This creates static files in the -`$PROJECT_ROOT/apps/.build` directory. +First, we need to build the documentation site via `$PROJECT_ROOT/scripts/generate.sh`. This creates static files in the +`$PROJECT_ROOT/.build` directory. ``` $PROJECT_ROOT ├── 📂 .build -│ ├── 📁 -│ ├── 📁 +│ ├── 📁 latest +│ ├── 📁 ``` ```sh -yarn run build-docs +yarn run docs:build ``` Second, we read the current contents of the `$BUILD_REPO/main` branch, this includes a `versions.json` file that lists @@ -50,10 +47,10 @@ Third, we update the `versions.json` file with the new version information, incl ```bash # cwd: $PROJECT_ROOT/.repo -node ../.github/update-versions.js +node ../scripts/update-versions.cjs ``` -Fourth, we copy the newly built static files from `$PROJECT_ROOT/apps/.build` into the appropriate directories in the +Fourth, we copy the newly built static files from `$PROJECT_ROOT/.build` into the appropriate directories in the documentation repository. If the directory exists, we overwrite its contents. If it does not exist, we create it. We only copy `latest` if the environment flag `BUILD_LATEST` is set to `true`. diff --git a/apps/docs/README.md b/apps/docs/README.md index 4dbddb9a..f5953586 100644 --- a/apps/docs/README.md +++ b/apps/docs/README.md @@ -10,11 +10,14 @@ Most scripts are prefixed. Scripts `docs:*` are scripts intended for CI/CD while Typically, you want to run this project in dev mode via `yarn run nuxt:dev:no-autogen`. This disables the template handler from running on Autogen on every route change. You can run `yarn run nuxt:prepare` to generate the `content` directory from `autogen` before running in dev mode. ### Known Issues -> :warning: Running `nuxt:prepare` while the dev server is running will break the dev server until it is restarted. This is expected behavior as `nuxt:prepare` modifies the `.nuxt` directory. +> [!WARNING] +> Running `nuxt:prepare` while the dev server is running will break the dev server until it is restarted. This is expected behavior as `nuxt:prepare` modifies the `.nuxt` directory. -> :warning: The handler is light and can run efficiently on route transition but it results in issues with `@nuxt/content` when run with many files. +> [!WARNING] +> The handler is light and can run efficiently on route transition but it results in issues with `@nuxt/content` when run with many files. -> :warning: If you are getting weird issues with the dev server, try stopping it, remove the `.nuxt` directory, and re-run via `yarn run nuxt:prepare` followed by `yarn run nuxt:dev:no-autogen`. +> [!WARNING] +> If you are getting weird issues with the dev server, try stopping it, remove the `.nuxt` directory, and re-run via `yarn run nuxt:prepare` followed by `yarn run nuxt:dev:no-autogen`. ### Bypassing Confirmation Prompts Some scripts require confirmation before proceeding. You can bypass these prompts by using the handy [`yes`](https://en.wikipedia.org/wiki/Yes_(Unix)) command. For example: @@ -24,54 +27,35 @@ yes | yarn run docs:deploy ``` ### Overview of `docs:*` scripts +For the environment variables and options each script accepts, see [`scripts/README.md`](./scripts/README.md). + #### `docs:build` -Builds the site via `nuxt:build`. It will create a `.build` folder containing the following: +Builds the site via `nuxt:generate` (through `scripts/generate.sh`). It will create a `.build` folder containing the following: ``` 📂 (root) ├── 📂 .build -│ ├── 📁 -│ ├── 📁 +│ ├── 📁 latest +│ ├── 📁 └── ... ``` -The 📁 `latest` directory contains a build with `BASE_PATH='/'` while `` contains a build with `BASE_PATH='`. +The 📁 `latest` directory contains a build with `BASE_PATH='/'` while `` contains a build with `BASE_PATH='`. `latest` is only built when `BUILD_LATEST=true`. ##### Logging The output of `stdout` and `stderr` from the build process is captured in `.stdout.log` and `.stderr.log` respectively in the project root. -##### Known Issues -This script is known to get stuck sometimes due to Nuxt's build process, particularly, when run in the VSCode terminal on macOS. If this happens, try running the command in a different terminal (e.g., iTerm2, Terminal.app) or simply re-running the command. You will know the build is stuck if you find this message in `.stdout.log` at the end of the file with no further output after it for more than a few seconds: - -``` -[nuxi] ✔ You can now deploy .output/public to any static hosting! -``` Keep in mind this script may take several minutes to complete. -##### Options -- (via environment) `BUILD_LATEST`: builds the `.build/latest` directory. -- (via environment) `PRODUCT_VERSION`: sets the product version for the build. - #### `docs:generate-manual` Generates the NetLogo User Manual from a build. The `.build/latest` directory must exist prior to running this command or it will ask you to run `docs:build` first. The generated PDF will be placed at the top level of `.build/latest` and `.build/`. -##### Options -- (via environment) `PRODUCT_VERSION`: sets the product version for the build, visible in the title page of the generated PDF. -- (via environment) `PORT`: sets the port for the preview server. Default: `3002`. - #### `docs:deploy` Documented in detail in [deploying the documentation site](./DEPLOYMENT.md). In short, it handles the commit to the github repository. -##### Options -- (via environment) `PROJECT_ROOT`: sets the project root for the build (usually: `.`). -- (via environment) `PRODUCT_DISPLAY_NAME`: sets the product display name for the build. -- (via environment) `PRODUCT_VERSION`: sets the product version for the build. -- (via environment) `BUILD_REPO`: sets the repository to push the built documentation to. -- (via environment) `BUILD_BRANCH`: sets the branch to push the built documentation to. - #### `docs:all` -Runs `docs:build`, `docs:generate-manual`, and `docs:deploy` in sequence. +Runs `docs:clean-up`, `docs:build`, `docs:generate-manual`, and `docs:deploy` in sequence. ##### Benchmark On M1 MacBook Air (2020): @@ -82,8 +66,8 @@ On M1 MacBook Air (2020): #### `docs:preview` Previews the documentation site locally. If `latest` exists, it unrolls it in a `.preview` directory for previewing. Otherwise, it uses the `PRODUCT_VERSION` directory. -#### `docs:make-static-site` -Creates a static export of the documentation site in `.build-static`. Static here refers to a site that can be loaded via the `file://` protocol. It uses relative paths and inlining for all assets. This exports only a subset of directories: the home page and top-level manual pages. It does not support javascript. +#### `docs:build:offline` +Creates an offline build of the site in `.build/latest`, loadable via the `file://` protocol. It runs `nuxt:generate` with `DOCS_ENV_STATIC=1`, then generates the PDF manual. #### `docs:clean-up` Cleans up all build and preview artifacts. diff --git a/apps/docs/app/app.vue b/apps/docs/app/app.vue index 47161f3f..e8b95f41 100644 --- a/apps/docs/app/app.vue +++ b/apps/docs/app/app.vue @@ -6,3 +6,13 @@ + + \ No newline at end of file diff --git a/apps/docs/app/components/ClientFooter.vue b/apps/docs/app/components/ClientFooter.vue index a0adf968..d2b924b6 100644 --- a/apps/docs/app/components/ClientFooter.vue +++ b/apps/docs/app/components/ClientFooter.vue @@ -47,7 +47,7 @@