Skip to content

Commit 710a025

Browse files
azeeyj-riveroahcordescpeters
authored
Build documentation using Sphinx (#441)
Uses sphinx to build the documentation contained in this repository. --------- Signed-off-by: Addisu Z. Taddese <[email protected]> Signed-off-by: Jose Luis Rivero <[email protected]> Signed-off-by: Steve Peters <[email protected]> Co-authored-by: Jose Luis Rivero <[email protected]> Co-authored-by: Alejandro Hernández Cordero <[email protected]> Co-authored-by: Steve Peters <[email protected]>
1 parent b6552cb commit 710a025

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

50 files changed

+1573
-165
lines changed

Diff for: ‎.github/workflows/deploy.yml

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
2+
name: Deploy Website and Docs
3+
4+
on:
5+
pull_request:
6+
push:
7+
branches:
8+
- master
9+
10+
# Allows you to run this workflow manually from the Actions tab
11+
workflow_dispatch:
12+
13+
jobs:
14+
build_website:
15+
runs-on: ubuntu-latest
16+
steps:
17+
# Build website from gazebosim-web-frontend
18+
- name: Checkout
19+
uses: actions/checkout@v4
20+
with:
21+
repository: gazebo-web/gazebosim-web-frontend
22+
ref: main
23+
- name: Setup Node
24+
uses: actions/setup-node@v4
25+
with:
26+
node-version: "20"
27+
cache: npm
28+
cache-dependency-path: package-lock.json
29+
- name: Setup Pages
30+
id: pages
31+
uses: actions/configure-pages@v5
32+
- name: Install Website dependencies
33+
run: npm ci
34+
- name: Build Website
35+
run: npm run build -- --base-href "${{ steps.pages.outputs.base_url }}/"
36+
# Upload the artifact for local preview
37+
- name: Upload artifact
38+
uses: actions/upload-artifact@v4
39+
with:
40+
name: website
41+
path: dist
42+
43+
# Build Docs
44+
build_docs:
45+
runs-on: ubuntu-latest
46+
steps:
47+
- name: Checkout
48+
uses: actions/checkout@v4
49+
- name: Setup Pages
50+
id: pages
51+
uses: actions/configure-pages@v5
52+
- name: Setup Python
53+
uses: actions/setup-python@v5
54+
with:
55+
python-version: '3.12'
56+
cache: 'pip'
57+
- name: Install Docs dependencies
58+
run: pip install -r requirements.txt
59+
- name: Build Docs
60+
run: python build_multiversion.py --pointers --libs --output_dir .build
61+
env:
62+
GZ_DEPLOY_URL: "${{ steps.pages.outputs.base_url }}"
63+
64+
# Upload the artifact for local preview
65+
- name: Upload artifact
66+
uses: actions/upload-artifact@v4
67+
with:
68+
name: docs
69+
path: .build
70+
71+
deploy:
72+
runs-on: ubuntu-latest
73+
needs: [build_website, build_docs]
74+
permissions:
75+
contents: write
76+
# Allow only one concurrent deployment between this and the nightly-upload workflow.
77+
concurrency:
78+
group: pages
79+
cancel-in-progress: false
80+
steps:
81+
- uses: actions/download-artifact@v4
82+
with:
83+
merge-multiple: true
84+
- name: Upload merged
85+
uses: actions/upload-artifact@v4
86+
with:
87+
name: website-docs-merged
88+
path: ./
89+
- name: Commit
90+
uses: peaceiris/actions-gh-pages@v4
91+
# The workflow upto this point is good for generating a preview,
92+
# but only commit to deploy if we are on the master branch (not a pull request).
93+
if: github.ref == 'refs/heads/master'
94+
with:
95+
github_token: ${{ secrets.GITHUB_TOKEN }}
96+
publish_dir: ./
97+
keep_files: true

Diff for: ‎.github/workflows/nightly-upload.yml

+12-13
Original file line numberDiff line numberDiff line change
@@ -58,17 +58,14 @@ jobs:
5858
needs: build
5959
runs-on: ubuntu-latest
6060
permissions:
61-
id-token: write
62-
contents: read
61+
contents: write
62+
# Allow only one concurrent deployment between this and the deploy workflow.
63+
concurrency:
64+
group: pages
65+
cancel-in-progress: false
6366
steps:
6467
- name: Checkout
6568
uses: actions/checkout@v4
66-
- name: Configure AWS Credentials
67-
id: creds
68-
uses: aws-actions/configure-aws-credentials@v4
69-
with:
70-
aws-region: us-east-1
71-
role-to-assume: arn:aws:iam::200670743174:role/github-oidc-deployment-gz-web-app
7269
- uses: actions/download-artifact@v4
7370
id: download
7471
with:
@@ -81,8 +78,10 @@ jobs:
8178
with:
8279
name: api-docs
8380
path: .api-out/*
84-
- name: Run nightly upload
85-
run: aws s3 sync .api-out/ s3://gazebosim.org/api/
86-
- name: Invalidate Cloudfront distribution
87-
run: |
88-
aws cloudfront create-invalidation --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} --paths '/*' --region us-east-1
81+
- name: Commit
82+
uses: peaceiris/actions-gh-pages@v4
83+
with:
84+
github_token: ${{ secrets.GITHUB_TOKEN }}
85+
publish_dir: ./.api-out
86+
destination_dir: api
87+
keep_files: true

Diff for: ‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.build
2+
.tmp
3+
.venv

Diff for: ‎README.md

+39-3
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,45 @@ found under the `API Reference` section of [https://gazebosim.org/docs](https://
1515

1616
## Main docs
1717

18-
The documentation in this repository is updated whenever the
19-
[gazebosim-web-backend](https://github.com/gazebo-web/gazebosim-web-backend),
20-
is deployed. The gazebosim-web-backend webserver maintains a clone of this repository, and serves the markdown pages to https://gazebosim.org/docs.
18+
The documentation in this repository is built using [Sphinx](https://www.sphinx-doc.org/).
19+
To build, you need to install the following:
20+
21+
* python virtualenv
22+
23+
Create the virtual env and activate it:
24+
25+
```bash
26+
python3 -m venv .venv
27+
source .venv/bin/activate
28+
```
29+
30+
Then install the necessary dependencies:
31+
32+
```bash
33+
pip install -r requirements.txt
34+
```
35+
36+
```bash
37+
python3 build_multiversion.py
38+
```
39+
40+
This will build all the documentation for all versions of Gazebo.
41+
You can preview the result locally by running an HTTP server on
42+
the output directory `.build`. For example:
43+
44+
```bash
45+
python3 -m http.server 8000 -d .build
46+
47+
```
48+
49+
This will serve the website on <http://localhost:8000>
50+
51+
For quicker iteration, you can build the documentation for a subset
52+
of Gazebo versions. To build `garden` and `harmonic`:
53+
54+
```bash
55+
python3 build_multiversion.py --release garden harmonic
56+
```
2157

2258
## Library docs
2359

Diff for: ‎_static/css/gazebo.css

+149
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
html {
2+
--pst-font-family-base: Roboto, var(--pst-font-family-base-system);
3+
--pst-font-size-base: 14px;
4+
--pst-header-height: 64px;
5+
--gz-doc-header-height: 120px;
6+
scroll-padding-top: calc(var(--pst-header-height) + var(--gz-doc-header-height) + 1rem);
7+
}
8+
9+
html[data-theme="light"] {
10+
--gz-color-doc-header: #4fc3f7;
11+
--gz-color-doc-header-text: #fff;
12+
--pst-color-primary: #0277bd;
13+
--gz-color-primary-sidebar: #f8f9fa;
14+
}
15+
16+
html[data-theme="dark"] {
17+
--gz-color-doc-header: rgb(15 23 36 / 30%);
18+
--gz-color-doc-header-text: #fff;
19+
--pst-color-primary: #0277bd;
20+
--gz-color-primary-sidebar: #1a1c1e;
21+
--pst-color-background: #131416;
22+
}
23+
24+
a {
25+
text-decoration: none;
26+
}
27+
28+
pre {
29+
border: none;
30+
}
31+
.bd-main .bd-content .bd-article-container {
32+
max-width: 160em;
33+
}
34+
35+
.bd-page-width {
36+
max-width: 100%;
37+
}
38+
39+
.bd-sidebar {
40+
max-width: 20em;
41+
}
42+
43+
.sidebar-primary-items__end {
44+
display: none;
45+
}
46+
47+
.bd-links__title {
48+
display: none;
49+
}
50+
51+
.navbar-nav .nav-item {
52+
letter-spacing: normal;
53+
text-transform: uppercase;
54+
font-size: 16px;
55+
text-decoration: none;
56+
outline: 0;
57+
transition: 0.5s;
58+
font-weight: 400;
59+
color: #6e6e6e;
60+
border-bottom: 1px solid rgba(0, 0, 0, 0);
61+
}
62+
.navbar-nav li a {
63+
margin-right: 20px;
64+
}
65+
66+
.bd-header .navbar-header-items {
67+
padding-left: 5em;
68+
}
69+
70+
.nav-link.nav-external:after {
71+
display: none;
72+
}
73+
74+
.doc-header {
75+
width: 100%;
76+
background-color: var(--gz-color-doc-header);
77+
color: var(--gz-color-doc-header-text);
78+
height: var(--gz-doc-header-height);
79+
}
80+
81+
.banner {
82+
align-items: center;
83+
padding: 20px 40px;
84+
place-content: center space-between;
85+
height: 100%;
86+
}
87+
88+
header.navbar {
89+
display: block;
90+
}
91+
92+
.bd-sidebar-primary {
93+
max-height: calc(100vh - var(--pst-header-height) + var(--gz-doc-header-height));
94+
top: calc(var(--pst-header-height) + var(--gz-doc-header-height));
95+
background-color: var(--gz-color-primary-sidebar);
96+
}
97+
98+
.bd-sidebar-secondary {
99+
max-height: calc(100vh - var(--pst-header-height) + var(--gz-doc-header-height));
100+
top: calc(var(--pst-header-height) + var(--gz-doc-header-height));
101+
}
102+
103+
.gz-version-switcher {
104+
display: flex;
105+
}
106+
button.btn.version-switcher__button {
107+
color: var(--gz-color-doc-header-text);
108+
border-color: var(--gz-color-doc-header-text);
109+
}
110+
.bd-header-version-info {
111+
background-color: var(--pst-color-info-bg);
112+
}
113+
114+
.navbar-brand img {
115+
height: 84px;
116+
}
117+
118+
.warning {
119+
border-left: 3px solid rgb(228, 167, 2);
120+
padding: 15px;
121+
margin: 15px 0;
122+
color: #8a6c40;
123+
background: rgb(252, 248, 228);
124+
}
125+
126+
/* Style for /libs */
127+
.gz-libs-lists {
128+
display: inline;
129+
padding: 0;
130+
}
131+
132+
.gz-libs-lists p {
133+
display: inline;
134+
}
135+
136+
.gz-libs-lists li, .gz-libs-cards li {
137+
list-style-type: none;
138+
display: inline;
139+
padding-left: 0px;
140+
padding-right: 30px;
141+
}
142+
143+
.gz-libs-cards ul {
144+
padding-left: 1em;
145+
}
146+
147+
.gz-libs-cards .sd-card-text {
148+
display: inline;
149+
}

Diff for: ‎_static/icon/favicon.ico

14.1 KB
Binary file not shown.

0 commit comments

Comments
 (0)