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]>
gazebosim · Jul 11, 2024 · 710a025 · 710a025
1 parent b6552cb
commit 710a025
Show file tree

Hide file tree

Showing 50 changed files with 1,573 additions and 165 deletions.
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -0,0 +1,97 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+name: Deploy Website and Docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build_website:
+    runs-on: ubuntu-latest
+    steps:
+      # Build website from gazebosim-web-frontend
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: gazebo-web/gazebosim-web-frontend
+          ref: main
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Install Website dependencies
+        run: npm ci
+      - name: Build Website
+        run: npm run build -- --base-href "${{ steps.pages.outputs.base_url }}/"
+      # Upload the artifact for local preview
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: website
+          path: dist
+
+      # Build Docs
+  build_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+      - name: Install Docs dependencies
+        run: pip install -r requirements.txt
+      - name: Build Docs
+        run: python build_multiversion.py --pointers --libs --output_dir .build
+        env:
+          GZ_DEPLOY_URL: "${{ steps.pages.outputs.base_url }}"
+
+      # Upload the artifact for local preview
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: .build
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: [build_website, build_docs]
+    permissions:
+      contents: write
+    # Allow only one concurrent deployment between this and the nightly-upload workflow.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          merge-multiple: true
+      - name: Upload merged
+        uses: actions/upload-artifact@v4
+        with:
+          name: website-docs-merged
+          path: ./
+      - name: Commit
+        uses: peaceiris/actions-gh-pages@v4
+        # The workflow upto this point is good for generating a preview,
+        # but only commit to deploy if we are on the master branch (not a pull request).
+        if: github.ref == 'refs/heads/master'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./
+          keep_files: true
diff --git a/.github/workflows/nightly-upload.yml b/.github/workflows/nightly-upload.yml
@@ -58,17 +58,14 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     permissions:
-      id-token: write
-      contents: read
+      contents: write
+    # Allow only one concurrent deployment between this and the deploy workflow.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
     steps:
     - name: Checkout
       uses: actions/checkout@v4
-    - name: Configure AWS Credentials
-      id: creds
-      uses: aws-actions/configure-aws-credentials@v4
-      with:
-        aws-region: us-east-1
-        role-to-assume: arn:aws:iam::200670743174:role/github-oidc-deployment-gz-web-app
     - uses: actions/download-artifact@v4
       id: download
       with:
@@ -81,8 +78,10 @@ jobs:
       with:
         name: api-docs
         path: .api-out/*
-    - name: Run nightly upload
-      run: aws s3 sync .api-out/ s3://gazebosim.org/api/
-    - name: Invalidate Cloudfront distribution
-      run: |
-        aws cloudfront create-invalidation --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} --paths '/*' --region us-east-1
+    - name: Commit
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./.api-out
+        destination_dir: api
+        keep_files: true
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,3 @@
+.build
+.tmp
+.venv
diff --git a/README.md b/README.md
@@ -15,9 +15,45 @@ found under the `API Reference` section of [https://gazebosim.org/docs](https://
 
 ## Main docs
 
-The documentation in this repository is updated whenever the
-[gazebosim-web-backend](https://github.com/gazebo-web/gazebosim-web-backend),
-is deployed. The gazebosim-web-backend webserver maintains a clone of this repository, and serves the markdown pages to https://gazebosim.org/docs.
+The documentation in this repository is built using [Sphinx](https://www.sphinx-doc.org/).
+To build, you need to install the following:
+
+* python virtualenv
+
+Create the virtual env and activate it:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Then install the necessary dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+```bash
+python3 build_multiversion.py
+```
+
+This will build all the documentation for all versions of Gazebo.
+You can preview the result locally by running an HTTP server on
+the output directory `.build`. For example:
+
+```bash
+python3 -m http.server 8000 -d .build
+
+```
+
+This will serve the website on <http://localhost:8000>
+
+For quicker iteration, you can build the documentation for a subset
+of Gazebo versions. To build `garden` and `harmonic`:
+
+```bash
+python3 build_multiversion.py --release garden harmonic
+```
 
 ## Library docs
 

diff --git a/_static/css/gazebo.css b/_static/css/gazebo.css
@@ -0,0 +1,149 @@
+html {
+  --pst-font-family-base: Roboto, var(--pst-font-family-base-system);
+  --pst-font-size-base: 14px;
+  --pst-header-height: 64px;
+  --gz-doc-header-height: 120px;
+  scroll-padding-top: calc(var(--pst-header-height) + var(--gz-doc-header-height) + 1rem);
+}
+
+html[data-theme="light"] {
+  --gz-color-doc-header: #4fc3f7;
+  --gz-color-doc-header-text: #fff;
+  --pst-color-primary: #0277bd;
+  --gz-color-primary-sidebar: #f8f9fa;
+}
+
+html[data-theme="dark"] {
+  --gz-color-doc-header: rgb(15 23 36 / 30%);
+  --gz-color-doc-header-text: #fff;
+  --pst-color-primary: #0277bd;
+  --gz-color-primary-sidebar: #1a1c1e;
+  --pst-color-background: #131416;
+}
+
+a {
+  text-decoration: none;
+}
+
+pre {
+  border: none;
+}
+.bd-main .bd-content .bd-article-container {
+  max-width: 160em;
+}
+
+.bd-page-width {
+  max-width: 100%;
+}
+
+.bd-sidebar {
+  max-width: 20em;
+}
+
+.sidebar-primary-items__end {
+  display: none;
+}
+
+.bd-links__title {
+  display: none;
+}
+
+.navbar-nav .nav-item {
+  letter-spacing: normal;
+  text-transform: uppercase;
+  font-size: 16px;
+  text-decoration: none;
+  outline: 0;
+  transition: 0.5s;
+  font-weight: 400;
+  color: #6e6e6e;
+  border-bottom: 1px solid rgba(0, 0, 0, 0);
+}
+.navbar-nav li a {
+  margin-right: 20px;
+}
+
+.bd-header .navbar-header-items {
+  padding-left: 5em;
+}
+
+.nav-link.nav-external:after {
+  display: none;
+}
+
+.doc-header {
+  width: 100%;
+  background-color: var(--gz-color-doc-header);
+  color: var(--gz-color-doc-header-text);
+  height: var(--gz-doc-header-height);
+}
+
+.banner {
+  align-items: center;
+  padding: 20px 40px;
+  place-content: center space-between;
+  height: 100%;
+}
+
+header.navbar {
+  display: block;
+}
+
+.bd-sidebar-primary {
+  max-height: calc(100vh - var(--pst-header-height) + var(--gz-doc-header-height));
+  top: calc(var(--pst-header-height) + var(--gz-doc-header-height));
+  background-color: var(--gz-color-primary-sidebar);
+}
+
+.bd-sidebar-secondary {
+  max-height: calc(100vh - var(--pst-header-height) + var(--gz-doc-header-height));
+  top: calc(var(--pst-header-height) + var(--gz-doc-header-height));
+}
+
+.gz-version-switcher {
+  display: flex;
+}
+button.btn.version-switcher__button {
+  color: var(--gz-color-doc-header-text);
+  border-color: var(--gz-color-doc-header-text);
+}
+.bd-header-version-info {
+    background-color: var(--pst-color-info-bg);
+}
+
+.navbar-brand img {
+  height: 84px;
+}
+
+.warning {
+  border-left: 3px solid rgb(228, 167, 2);
+  padding: 15px;
+  margin: 15px 0;
+  color: #8a6c40;
+  background: rgb(252, 248, 228);
+}
+
+/* Style for /libs */
+.gz-libs-lists {
+  display: inline;
+  padding: 0;
+}
+
+.gz-libs-lists p {
+  display: inline;
+}
+
+.gz-libs-lists li, .gz-libs-cards li {
+  list-style-type: none;
+  display: inline;
+  padding-left: 0px;
+  padding-right: 30px;
+}
+
+.gz-libs-cards ul {
+  padding-left: 1em;
+}
+
+.gz-libs-cards .sd-card-text {
+  display: inline;
+}
diff --git a/_static/icon/favicon.ico b/_static/icon/favicon.ico