Skip to content

Commit bf807d2

Browse files
jgaucher-csjgaucher-cs
committed
feat: remove docs/doc/api/rest + cleaning
1 parent 47ba43f commit bf807d2

File tree

4 files changed

+45
-106
lines changed

4 files changed

+45
-106
lines changed

‎.github/actions/poetry-install/action.yml

-7
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,6 @@ inputs:
2020
description: "'poetry install' options e.g. '--with dev'"
2121
required: false
2222
default: --with dev
23-
24-
venv:
25-
description: "use the specificed virtual environment"
26-
required: false
27-
default: .venv
2823

2924
working-directory:
3025
description: "the working directory in which poetry is run."
@@ -37,8 +32,6 @@ runs:
3732
- uses: ./.github/actions/install-python
3833
- uses: snok/install-poetry@v1
3934
- run: |
40-
source ${{ inputs.venv }}/bin/activate
41-
poetry lock --no-update
4235
poetry install ${{ inputs.options }} # don't use quotes around options
4336
working-directory: ${{ inputs.working-directory }}
4437
shell: bash

‎.github/workflows/generate-documentation.yml

+22-60
Original file line numberDiff line numberDiff line change
@@ -33,26 +33,27 @@ jobs:
3333
steps:
3434
- uses: actions/checkout@v4
3535
- uses: ./.github/actions/install-python
36-
- name: Create the virtual env
37-
run: |
38-
python -m venv ~/env_rs_doc
39-
working-directory: .
40-
shell: bash
41-
- uses: ./.github/actions/poetry-install
42-
with:
43-
options: --no-root
44-
venv: ~/env_rs_doc
45-
working-directory: .
36+
4637
- name: Clone RS-Server/RS-Client/RS-Demo/RS-Infra/RS-Helm
4738
run: |
4839
set -x
4940
pwd
5041
ls -all
5142
cd docs
5243
44+
# We want to use the same branch name (if it exists) in the other
45+
# cloned repositories than the current branch name
46+
branch_name=${{ github.ref_name }}
47+
48+
#
5349
# Clone public rspy repositories
54-
git clone -b develop https://github.com/RS-PYTHON/rs-server.git
55-
git clone -b develop https://github.com/RS-PYTHON/rs-client-libraries.git
50+
51+
git clone https://github.com/RS-PYTHON/rs-server.git
52+
(cd rs-server; git checkout $branch_name || git checkout develop)
53+
54+
git clone https://github.com/RS-PYTHON/rs-client-libraries.git
55+
(cd rs-client-libraries; git checkout $branch_name || git checkout develop)
56+
5657
ls -all
5758
5859
# Clone private rspy repositories.
@@ -63,12 +64,14 @@ jobs:
6364
# https://github.com/RS-PYTHON/rs-helm/settings/keys
6465
eval "$(ssh-agent -s)"
6566
ssh-add - <<< "${{ secrets.RS_DEMO_PRIVATE_SSH_KEY }}"
66-
git clone -b develop [email protected]:RS-PYTHON/rs-demo.git
67+
git clone [email protected]:RS-PYTHON/rs-demo.git
68+
(cd rs-demo; git checkout $branch_name || git checkout develop)
6769
6870
eval "$(ssh-agent -s)"
6971
ssh-add - <<< "${{ secrets.RS_INFRA_PRIVATE_SSH_KEY }}"
70-
git clone -b develop --depth 1 [email protected]:RS-PYTHON/rs-infrastructure.git
72+
git clone --depth 1 [email protected]:RS-PYTHON/rs-infrastructure.git
7173
cd rs-infrastructure
74+
git checkout $branch_name || git checkout develop
7275
git sparse-checkout init --no-cone
7376
echo "/docs/" > .git/info/sparse-checkout
7477
echo "/LICENSE" >> .git/info/sparse-checkout
@@ -80,61 +83,20 @@ jobs:
8083
8184
eval "$(ssh-agent -s)"
8285
ssh-add - <<< "${{ secrets.RS_HELM_PRIVATE_SSH_KEY }}"
83-
git clone -b develop [email protected]:RS-PYTHON/rs-helm.git
86+
git clone [email protected]:RS-PYTHON/rs-helm.git
87+
(cd rs-helm; git checkout $branch_name || git checkout develop)
8488
working-directory: .
85-
shell: bash
86-
# # The technical documentation uses a dedicated python project to be built
87-
# - uses: ./.github/actions/poetry-install
88-
# with:
89-
# working-directory: ./docs/rs-server/
90-
91-
# To pull ghcr.io/rs-python/apikey-manager
92-
# TODO: to be changed when the apikey manager will have its own container registry.
93-
- name: Log into Docker registry
94-
uses: docker/login-action@v3
95-
with:
96-
registry: ghcr.io
97-
username: ${{ github.actor }}
98-
password: ${{ secrets.GITHUB_TOKEN }}
99-
100-
- name: Generate REST API (Swagger) HTML documentation
101-
run: |
102-
set -x
103-
pwd
104-
ls -all
105-
sleep 2
106-
cd docs/rs-server/
107-
# Generate the aggregated openapi.json/swagger
108-
echo 'Generate the aggregated openapi.json/swagger'
109-
./services/frontend/resources/build_aggregated_openapi.sh --run-services --set-version
110-
111-
# Copy it beside the index.html
112-
echo 'Copy openapi.json in rest directory'
113-
cp ./services/frontend/resources/openapi.json ./docs/doc/api/rest/
11489
shell: bash
11590

116-
# - name: Deploy docs to ghpages
117-
# uses: peaceiris/actions-gh-pages@v4
118-
# with:
119-
# github_token: ${{ secrets.GITHUB_TOKEN }}
120-
# publish_branch: gh-pages
121-
# publish_dir: ./site
122-
123-
- uses: ./.github/actions/poetry-install
124-
with:
125-
venv: ~/env_rs_doc
126-
working-directory: ./docs/rs-server
127-
- uses: ./.github/actions/poetry-install
128-
with:
129-
venv: ~/env_rs_doc
130-
working-directory: ./docs/rs-client-libraries
91+
- name: Install dependencies
92+
uses: ./.github/actions/poetry-install
93+
13194
- name: Generate Markdown HTML documentation
13295
run: |
13396
set -x
13497
pwd
13598
ls -all
13699
sleep 2
137-
source ~/env_rs_doc/bin/activate
138100
poetry run mkdocs gh-deploy --force
139101
working-directory: .
140102
shell: bash

‎docs/how_to.md

+20-34
Original file line numberDiff line numberDiff line change
@@ -16,51 +16,37 @@ Prepare the environment
1616
=======================
1717
1. Clone the rs-documentation repository:
1818
```shell
19-
#: git clone https://github.com/RS-PYTHON/rs-documentation.git
20-
#: cd rs-documentation
19+
git clone https://github.com/RS-PYTHON/rs-documentation.git
20+
cd rs-documentation
2121
```
22-
2. Create a virtual env and activate it:
22+
23+
2. Clone the RS-Server, RS-Client, RS-Demo, RS-Infrastructure and RS-Helm repositories. The default branch from which
24+
the projects are pulled is 'develop', but one can choose whatever branch is needed by using '-b' flag.
25+
26+
**NOTE**: The repositories need to be pulled in 'docs' directory
27+
28+
**NOTE**: The RS-Demo, RS-Infrastructure and RS-Helm repositories are not public, so a github access is needed
2329
```shell
24-
#: python -m venv env_rs_doc
25-
#: source env_rs_doc/bin/activate
30+
cd docs
31+
git clone -b develop https://github.com/RS-PYTHON/rs-server.git
32+
git clone -b develop https://github.com/RS-PYTHON/rs-client-libraries.git
33+
git clone -b develop [email protected]:RS-PYTHON/rs-demo.git
34+
git clone -b develop [email protected]:RS-PYTHON/rs-infrastructure.git
35+
git clone -b develop [email protected]:RS-PYTHON/rs-helm.git
36+
cd ..
2637
```
38+
2739
3. Install needed rs-documentation packages:
2840
```shell
29-
#: poetry install --no-root
30-
```
31-
4. Clone the RS-Server, RS-Client, RS-Demo, RS-Infrastructure and RS-Helm repositories. The default branch from which
32-
the projects are pulled is 'main', but one can choose whatever branch is needed by using '-b' flag
33-
**NOTE**: The repositories need to be pulled in 'docs' directory
34-
**NOTE**: The RS-Demo, RS-Infrastructure and RS-Helm repositories are not public, so a github access is needed
35-
```shell
36-
#: cd docs
37-
#: git clone -b develop https://github.com/RS-PYTHON/rs-server.git
38-
#: git clone -b develop https://github.com/RS-PYTHON/rs-client-libraries.git
39-
#: git clone -b feat-rspy112/improve-documentation [email protected]:RS-PYTHON/rs-demo.git
40-
#: git clone -b feat-rspy112/improve-documentation [email protected]:RS-PYTHON/rs-infrastructure.git
41-
#: git clone -b feat-rspy112/improve-documentation [email protected]:RS-PYTHON/rs-helm.git
42-
#: cd ..
43-
```
44-
5. Install the source code python packages:
45-
```shell
46-
#: cd rs-server
47-
#: poetry install --with-dev
48-
#: cd ../rs-client-libraries
49-
#: poetry install --with-dev
50-
#: cd ..
51-
```
52-
6. Generate the swagger html documentation for RS-Server and copy it in the needed directory:
53-
```shell
54-
#: ./rs-server/services/frontend/resources/build_aggregated_openapi.sh --run-services --set-version
55-
#: cp rs-server/services/frontend/resources/openapi.json rs-server/docs/doc/api/rest/
41+
poetry install
5642
```
5743

5844
Generate and integrate the documentation
5945
========================================
6046

6147
From the **rs-documentation directory**, execute the command:
6248
```shell
63-
#: mkdocs build
49+
poetry run mkdocs build
6450
```
6551

6652
This command generates the html pages of all the technical documentation as well as for the static documentation
@@ -78,7 +64,7 @@ the /docs endpoint.
7864

7965
You can verify the generated documentation before publishing it. mkdocs may be used to serve the generated site:
8066
```shell
81-
#: mkdocs serve
67+
poetry run mkdocs serve
8268
```
8369

8470
Important elements to check :

‎pyproject.toml

+3-5
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,19 @@
11
[project]
22
name = "rs-documentation"
33
version = "0.0.0" # see: https://github.com/mtkennerly/poetry-dynamic-versioning
4-
package-mode = false
54

65
[tool.poetry]
76
name = "rs-documentation"
87
version = "0.0.0"
98
description = ""
109
authors = ["Your Name <[email protected]>"]
1110
readme = "README.md"
11+
package-mode = false
1212

13-
# This root project is not used in release production.
14-
# It's only used by the CI/CD to run pytest, pylint, mypy etc... on the whole github project.
15-
16-
# All the dependencies for release are set in the sub-projects
1713
[tool.poetry.dependencies]
1814
python = "^3.11"
15+
rs-server = {path = "docs/rs-server", develop = true}
16+
rs-client-libraries = {path = "docs/rs-client-libraries", develop = true}
1917
mkdocs = "^1.6.0"
2018
mkdocs-material = "^9.5.23"
2119
mkdocstrings = "^0.25.1"

0 commit comments

Comments
 (0)