From ff9c4d1039b5ecc03af8c8eb7b3f6aa899d0069b Mon Sep 17 00:00:00 2001 From: Hugo Venturini Date: Thu, 22 May 2025 17:57:48 +0200 Subject: [PATCH 1/5] enhance www/README.md --- www/README.md | 98 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 70 insertions(+), 28 deletions(-) diff --git a/www/README.md b/www/README.md index 53c7aed3f..c0b0f3d24 100644 --- a/www/README.md +++ b/www/README.md @@ -1,44 +1,86 @@ -# Website +# Skip Documentation Website -The documentation website is built using [Docusaurus](https://docusaurus.io/). +This website is built using [Docusaurus](https://docusaurus.io/) and hosts both our documentation and blog. +## API Documentation -# API Documentation +The API documentation is generated using: +- [TypeDoc](https://typedoc.org/index.html) for API documentation generation +- [docusaurus-plugin-typedoc](https://typedoc-plugin-markdown.org/plugins/docusaurus) for Docusaurus integration -The API docs are generated by [TypeDoc](https://typedoc.org/index.html) and integrated into docusaurus using [docusaurus-plugin-typedoc](https://typedoc-plugin-markdown.org/plugins/docusaurus). -This setup needs the development/source docs site to be in the same repo as the sources, as there are relative paths in the docusaurus config file to the sources. -A separate deployment step will be needed to generate the docs and push them to the repo that feeds the live site. -This also means that we can iterate on the docs in the source repo without publishing them immediately, and then choose to publish them in sync with publishing packages. +### Development Setup -The workflow for working on API docs is: -``` -- $ cd /path/to/repo/root -- $ make docs # to initialize the api docs -- $ make docs-run # to run the docs site locally -- visit http://localhost:3000/docs/api/core -- edit the doc comments in the sources -- $ make docs # to regenerate the api docs +The development/source docs site must be in the same repository as the source code due to relative paths in the Docusaurus configuration. This setup allows us to: +- Iterate on documentation in the source repository +- Choose when to publish documentation +- Keep documentation in sync with package releases + +### Development Workflow + +#### Standard Workflow +```bash +# From repository root INSIDE your Docker instance +make docs # Initialize API documentation ``` -A faster but not robust way to regenerate the api docs is: + +```bash +# From repository rood OUTSIDE your Docker instance +make docs-run # Run the docs site locally +# Visit http://localhost:3000/docs/api/core or http://localhost/blog + +# After editing doc comments in the sources +make docs # Regenerate API documentation ``` -- cd /path/to/repo/root/www && npx docusaurus generate-typedoc + +### Publishing Documentation + +Before, commit your changes and send them for review +```bash +git add +git commit -m '' +gh pr create # if you use the GitHub CLI ``` -To publish the docs to the live site: + +When reviewed and mereged, rebase and clean up your repository: +```bash +git pull --rebase +git clean -Xdn # -n for a dry-run and double-check what's to be cleaned out +git clean -Xdf # the actual cleaning ``` -- $ make docs-publish + + +To publish documentation to the live site: +```bash +# From repository root INSIDE your Docker instance +make docs-publish ``` -This will suggest to run: + +Note the the hash of your commit: +```bash +git rev-parse --short HEAD # supposingly it is the last commit of the branch ``` -Test locally: make docs-serve -Push to live site: cd www/docs_site/; git add -A; git commit -m 'update to '; git push; cd - + +This will suggest running: +```bash +# Test locally +make docs-serve + +# Push to live site +cd www/docs_site/ +git add -A +git commit -m 'update to ' +git push +cd - ``` -Note that the docs_site commit messages will mention the wrong commit hashes if `make docs-publish` is run from a commit that is not (an ancestor of) `main`. -The documentation for the tags that TypeDoc recognizes is -[here](https://typedoc.org/guides/tags/). +> **Note**: If `make docs-publish` is run from a commit that is not (an ancestor of) `main`, the docs_site commit messages will contain incorrect commit hashes. + +## Documentation Structure -Once the docs site is running at http://localhost:3000, the markdown documentation under `www/docs` can be edited and the changes are usually picked up automatically. +- The markdown documentation under `www/docs` can be edited while the site is running at http://localhost:3000 +- Changes to the `www/docs` file structure must be reflected in `www/sidebars.ts` +- The `docusaurus.config.ts` file is sensitive to the file system locations of source entry points and tsconfig files -Changes to the `www/docs` file structure usually need to be reflected in the `www/sidebars.ts` file. +## TypeDoc Tags -The `docusaurus.config.ts` file is sensitive to the file system locations of the source entry points and tsconfig files. +For a complete reference of TypeDoc tags, see the [official documentation](https://typedoc.org/guides/tags/). From b0bc7ad07072bbc96b43e4bc1d8c0606f716aae5 Mon Sep 17 00:00:00 2001 From: Hugo Venturini Date: Fri, 23 May 2025 14:17:55 +0200 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Josh Berdine --- www/README.md | 42 ++++++++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/www/README.md b/www/README.md index c0b0f3d24..aca985267 100644 --- a/www/README.md +++ b/www/README.md @@ -32,6 +32,11 @@ make docs-run # Run the docs site locally make docs # Regenerate API documentation ``` +A faster but not robust way to regenerate the api docs is: +```bash +cd /path/to/repo/root/www && npx docusaurus generate-typedoc +``` + ### Publishing Documentation Before, commit your changes and send them for review @@ -41,25 +46,20 @@ git commit -m '' gh pr create # if you use the GitHub CLI ``` -When reviewed and mereged, rebase and clean up your repository: -```bash -git pull --rebase -git clean -Xdn # -n for a dry-run and double-check what's to be cleaned out -git clean -Xdf # the actual cleaning -``` - - -To publish documentation to the live site: +When reviewed and mereged, you are ready to publish documentation to the live site: ```bash # From repository root INSIDE your Docker instance make docs-publish ``` -Note the the hash of your commit: +You should eventually read: ```bash -git rev-parse --short HEAD # supposingly it is the last commit of the branch +Test locally: make docs-serve +Push to live site: cd www/docs_site/; git add -A; git commit -m 'update to '; git push; cd - ``` +The commit hash in the last line should be the hash of your commit in the skip repository. + This will suggest running: ```bash # Test locally @@ -83,4 +83,22 @@ cd - ## TypeDoc Tags -For a complete reference of TypeDoc tags, see the [official documentation](https://typedoc.org/guides/tags/). +You may refer to the [official documentation](https://typedoc.org/guides/tags/) of TypeDoc tags for more information. + + +## FAQ + +### What if my `docs_site` is not on the `main` branch ? +Clean up your repository is good idea at this point and then start the process again: +```bash +```bash +git pull --rebase +git clean -Xdn # -n for a dry-run and double-check what's to be cleaned out +git clean -Xdf # the actual cleaning +``` + +### What if the hash is not in the commit message suggested along the process ? +You can get it from the skip repository: +```bash +git rev-parse --short HEAD # supposingly it is the last commit of the branch +``` From c19bfcdd2f79006afbaeb1e5ab842513e70c82c9 Mon Sep 17 00:00:00 2001 From: Hugo Venturini Date: Thu, 22 May 2025 17:57:48 +0200 Subject: [PATCH 3/5] enhance www/README.md --- www/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/www/README.md b/www/README.md index aca985267..60e6d516e 100644 --- a/www/README.md +++ b/www/README.md @@ -102,3 +102,4 @@ You can get it from the skip repository: ```bash git rev-parse --short HEAD # supposingly it is the last commit of the branch ``` + From ba72f18d0ffaa46c489e7cdfd18658f14fcc191f Mon Sep 17 00:00:00 2001 From: Hugo Venturini Date: Tue, 3 Jun 2025 16:13:38 +0200 Subject: [PATCH 4/5] fix merge --- www/README.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/www/README.md b/www/README.md index 60e6d516e..45914b2fa 100644 --- a/www/README.md +++ b/www/README.md @@ -21,9 +21,7 @@ The development/source docs site must be in the same repository as the source co ```bash # From repository root INSIDE your Docker instance make docs # Initialize API documentation -``` -```bash # From repository rood OUTSIDE your Docker instance make docs-run # Run the docs site locally # Visit http://localhost:3000/docs/api/core or http://localhost/blog @@ -91,10 +89,9 @@ You may refer to the [official documentation](https://typedoc.org/guides/tags/) ### What if my `docs_site` is not on the `main` branch ? Clean up your repository is good idea at this point and then start the process again: ```bash -```bash -git pull --rebase -git clean -Xdn # -n for a dry-run and double-check what's to be cleaned out -git clean -Xdf # the actual cleaning +git pull --rebase # ensure that your local docs_site submodule is up-to-date +git clean -Xdn # -n for a dry-run and double-check what's to be cleaned out +git clean -Xdf # the actual cleaning ``` ### What if the hash is not in the commit message suggested along the process ? From ef9ea017efa43d6b2b5fa0362eaead57587e8679 Mon Sep 17 00:00:00 2001 From: Hugo Venturini Date: Wed, 4 Jun 2025 10:29:45 +0200 Subject: [PATCH 5/5] Josh's comments --- www/README.md | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/www/README.md b/www/README.md index 45914b2fa..52ed72a58 100644 --- a/www/README.md +++ b/www/README.md @@ -44,7 +44,7 @@ git commit -m '' gh pr create # if you use the GitHub CLI ``` -When reviewed and mereged, you are ready to publish documentation to the live site: +When reviewed and merged, you are ready to publish documentation to the live site: ```bash # From repository root INSIDE your Docker instance make docs-publish @@ -58,19 +58,6 @@ Push to live site: cd www/docs_site/; git add -A; git commit -m 'update to ' -git push -cd - -``` - > **Note**: If `make docs-publish` is run from a commit that is not (an ancestor of) `main`, the docs_site commit messages will contain incorrect commit hashes. ## Documentation Structure @@ -94,9 +81,8 @@ git clean -Xdn # -n for a dry-run and double-check what's to be cleaned out git clean -Xdf # the actual cleaning ``` -### What if the hash is not in the commit message suggested along the process ? +### What if the hash in the suggested commit message is not the hash of your commit? You can get it from the skip repository: ```bash git rev-parse --short HEAD # supposingly it is the last commit of the branch ``` -