From df7c9c3f20f8b2059f01e4fb2d84175cf03e51f1 Mon Sep 17 00:00:00 2001 From: Alexander Popel Date: Mon, 25 Aug 2025 15:24:08 +0300 Subject: [PATCH 1/4] documentation-update: use new scripts for v4.5 --- .../nightly-documentation-update.yml | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/.github/workflows/nightly-documentation-update.yml b/.github/workflows/nightly-documentation-update.yml index 8352497ba..2776fe961 100644 --- a/.github/workflows/nightly-documentation-update.yml +++ b/.github/workflows/nightly-documentation-update.yml @@ -23,11 +23,16 @@ jobs: NightlyDocumentationUpdate-v4_5: needs: NightlyDocumentationUpdate if: ${{ !cancelled() }} - uses: 51Degrees/common-ci/.github/workflows/nightly-documentation-update.yml@main - with: - repo-name: ${{ github.event.repository.name }} - org-name: ${{ github.event.repository.owner.login }} - branch: version/4.5 - dryrun: ${{ inputs.dryrun || false }} - secrets: - token: ${{ secrets.ACCESS_TOKEN }} + runs-on: ubuntu-latest + defaults: + run: + shell: pwsh + steps: + - uses: actions/checkout@v5 + with: + token: ${{ secrets.ACCESS_TOKEN }} + ref: version/4.5 + - env: + GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }} + run: ./ci/generate-documentation.ps1 -Version '4.5' + - run: ./ci/update-gh-pages.ps1 From 578c3cae208251305802284ca82f6d8428437317 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Mon, 25 Aug 2025 15:53:43 +0200 Subject: [PATCH 2/4] run only generate-documentation --- .github/workflows/nightly-documentation-update.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/nightly-documentation-update.yml b/.github/workflows/nightly-documentation-update.yml index 2776fe961..7dc75dcf5 100644 --- a/.github/workflows/nightly-documentation-update.yml +++ b/.github/workflows/nightly-documentation-update.yml @@ -35,4 +35,3 @@ jobs: - env: GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }} run: ./ci/generate-documentation.ps1 -Version '4.5' - - run: ./ci/update-gh-pages.ps1 From 1b81de2a6aa5cd4edf99be361f3f9221ae7accf6 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Wed, 10 Sep 2025 16:33:50 +0200 Subject: [PATCH 3/4] Update Documenting.md correct link to DoxyGen repo and pre-built binaries --- Documenting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documenting.md b/Documenting.md index 061354acf..d24c99b36 100644 --- a/Documenting.md +++ b/Documenting.md @@ -313,8 +313,8 @@ All terms should use the same format as the 51Degrees glossary, for capitals, hy ## Dependencies ### DoxyGen We use a customised build of DoxyGen. -The source code is available from the [DoxyGen](https://51degrees.visualstudio.com/Documentation/_git/DoxyGen) repository. However, building from source can be [fiddly](https://www.doxygen.nl/manual/install.html). -Pre-built binaries can be downloaded from Sharepoint for [Linux](https://51degrees.sharepoint.com/:u:/r/Product%20Team/doxygen-linux.zip?csf=1&web=1&e=fTWXlN) or [Windows](https://51degrees.sharepoint.com/:u:/r/Product%20Team/doxygen-win.zip?csf=1&web=1&e=T7MvWo). +The source code is available from the [DoxyGen](https://github.com/51Degrees/doxygen) repository. However, building from source can be [fiddly](https://www.doxygen.nl/manual/install.html). +Pre-built binaries can be downloaded from Sharepoint for [Linux](https://51degrees.sharepoint.com/:u:/r/Product%20Team/doxygen-linux.zip?csf=1&web=1&e=fTWXlN) or [Windows](https://51degrees.sharepoint.com/:u:/r/Product%20Team/doxygen-win.zip?csf=1&web=1&e=T7MvWo). The Linux pre-buit binaries also live in the [Tools Repo](https://github.com/51Degrees/tools/tree/main/DoxyGen). ### GraphVis In order for DoxyGen to generate nice diagrams, [GraphVis 2.38](https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi) must be installed. @@ -322,4 +322,4 @@ In order for DoxyGen to generate nice diagrams, [GraphVis 2.38](https://graphviz ### Pattern Lab The css used in all documentation comes from the pattern lab submodule. -To generate the `main.min.css` needed by the documentation, follow the installation instructions in the [PatternLab readme](patternlab/README.md) to generat the css, then run ``gulp minify-css`` to minify it. The minified css will now live in `patternlab/source/css`. \ No newline at end of file +To generate the `main.min.css` needed by the documentation, follow the installation instructions in the [PatternLab readme](patternlab/README.md) to generat the css, then run ``gulp minify-css`` to minify it. The minified css will now live in `patternlab/source/css`. From 31c5484cc39af1520ad2be9615aeb900fd8edb86 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Thu, 11 Sep 2025 12:13:45 +0200 Subject: [PATCH 4/4] Update README.md documentation build instructions using docker --- README.md | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 10009be2e..a4f3ec033 100644 --- a/README.md +++ b/README.md @@ -39,12 +39,15 @@ This is only intended to be performed by 51Degrees employees. ## Automatic -The documentation can be generated by using the [documentation](https://51degrees.visualstudio.com/Pipeline/_build?definitionScope=%5Cdocumentation) pipelines in Azure DevOps. +The documentation is generated using the GitHub Workflow `nightly-documentation-update.yml` that uploads the updated documentation +to `gh-pages` branch. -These will generate HTML for each of the APIs in turn, updating the gh-pages (or gh-pages-staging) branch with any changes. -The process will then repeat for this repository. +For version `4.4` and below each API repository generates its own documentation and uploads it to its own `gh-pages` branch. +Starting version `4.5` this repository has a self-sufficient `ci/generate-documentation.ps1` (currently on `version/4.5` branch) +script that checks out all API repositories, builds their documentation and transfers it to `4.5/apis` - that way we don't depend on +any other API repository workflow and all docs are hosted in a single location namely this repo gh-pages branch. -Once this process is complete, all gh-pages branches will have been updated and the website project can be updated to reference the new commits. +To add a new API repo - simply edit `ci/generate-documentation.ps1` (currently on `version/4.5` branch). ## Manual @@ -61,4 +64,24 @@ Simply run the DoxyWizard program and open the Doxyfile in the root of this repo Open a command line, navigate to the repository root and execute the command: `Doxygen`. +### Docker +If you have a pre-built linux binary of a Doxygen, you can use these commands that utilize the official `ubuntu` docker image, +note the directory layout and the `-v` flag (volume mounting) - so you need at least `documentation` repo cloned on your machine: + +This runs from the documentation directory and only requires your GITHUB_TOKEN to checkout all API repositories +(currently on `version/4.5` branch only): + +```sh +docker run --rm --platform linux/amd64 -v .:/media/documentation -w /media/documentation -e GITHUB_TOKEN="" ubuntu \ +pwsh ./ci/generate-documentation.ps1 -Version 4.5 -GenerateOnly +``` + +This is a shortcut version if you only need to regenerate the main documentation and do not need the API repositories: + +```sh +docker run --rm --platform linux/amd64 -v ./..:/media/51drepos -w /media/51drepos/documentation/docs ubuntu \ +../../tools/doxygen-linux +``` +This sets the working directory to `documentation/docs` and works provided that you have `doxygen-linux` binary located +in the `tools` directory on the same level as `documentation` directory.