diff --git a/.github/workflows/nightly-documentation-update.yml b/.github/workflows/nightly-documentation-update.yml index 8352497ba..7dc75dcf5 100644 --- a/.github/workflows/nightly-documentation-update.yml +++ b/.github/workflows/nightly-documentation-update.yml @@ -23,11 +23,15 @@ 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' 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`. 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.