Skip to content

Commit 1abdc04

Browse files
artivisjoansola
artivis
and
joansola
authored
Revamp the documentation (#324)
* revamp documentation * wip doc ci * wip doc ci lint * Update README.md * Add section and table with details on tangent spaces * add some examples of the tangent space * Add some note in the Jacobians section. Simplify the Tangent space section * wip python api doc * fix JOSS badge * wip fix equations * use boldsymbol * Use trailing spaces workaround for underscripts See github/markup#1575 --------- Signed-off-by: artivis <[email protected]> Signed-off-by: artivis <[email protected]> Co-authored-by: Joan Solà <[email protected]>
1 parent aeb2648 commit 1abdc04

Some content is hidden

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

59 files changed

+2949
-4003
lines changed

‎.codedocs

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎.github/workflows/docs.yml

Lines changed: 88 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,123 @@
11
name: documentation
2+
23
on:
34
push:
4-
branches: devel
5+
branches: [ devel ]
56
pull_request:
6-
branches:
7-
- devel
87
workflow_dispatch:
98

10-
jobs:
9+
concurrency:
10+
group: ${{ github.workflow }}-${{ github.ref }}
11+
cancel-in-progress: true
1112

12-
# There is no way as of now to move artifacts around jobs and
13-
# across workflows. So we build the Python bindings here too.
13+
jobs:
1414
build:
15-
runs-on: ubuntu-20.04
15+
runs-on: ubuntu-latest
1616
steps:
17-
18-
# Build manifpy
19-
2017
- name: Checkout
2118
uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
2222
- name: Set up Python
23-
uses: actions/setup-python@v2
23+
uses: actions/setup-python@v5
2424
with:
25-
python-version: 3.6
26-
- name: Setup apt
27-
run: |
28-
sudo apt update
29-
sudo apt install -y libeigen3-dev
30-
- name: Setup
31-
run: |
32-
python -m pip install --upgrade pip
33-
python -m pip install build
34-
- name: Build
35-
run: python -m pip install -v .
36-
37-
# build:
38-
# runs-on: ubuntu-20.04
39-
# needs: [pybind11]
40-
# steps:
41-
# - name: Checkout
42-
# uses: actions/checkout@v4
43-
# - name: Set up Python
44-
# uses: actions/setup-python@v2
45-
46-
# Build documentation website
47-
48-
- name: Fetch apt deps
25+
python-version: "3.12"
26+
27+
- name: Update sources
28+
run: sudo apt-get update
29+
30+
- name: Install doc dependencies
31+
run: sudo apt-get install -y doxygen
32+
33+
# Those are necessary if pip doesn't find the wheels
34+
# and decides to rebuild from source
35+
- name: Install doc extra dependencies
36+
run: sudo apt-get install -y libjpeg-dev libxml2-dev libxslt1-dev
37+
38+
- name: Install manif dependencies
39+
run: sudo apt-get install -y libeigen3-dev
40+
41+
- name: Build Sphinx venv
42+
working-directory: "docs"
4943
run: |
50-
sudo apt update
51-
sudo apt install -y libeigen3-dev flex bison graphicsmagick-imagemagick-compat
44+
set -ex
45+
make install || ( cat .sphinx/venv/pip_install.log && exit 1 )
5246
53-
- name: Make install Doxygen
47+
- name: Build documentation
48+
working-directory: docs
5449
run: |
55-
git clone --depth 1 --branch Release_1_9_1 https://github.com/doxygen/doxygen.git
56-
cd doxygen && mkdir build && cd build
57-
cmake -G "Unix Makefiles" ..
58-
sudo make install
59-
60-
- name: Fetch Python deps
61-
run: python -m pip install jinja2 Pygments docutils
62-
- name: Fetch m.css
50+
make html || ( echo "Whole bunch of things to fix." )
51+
if ! [ -d _build ]; then exit 1; fi
52+
53+
- name: Upload artifacts
54+
uses: actions/upload-artifact@v4
55+
with:
56+
name: doc
57+
path: |
58+
docs/_build
59+
!docs/_build/doxyxml
60+
61+
test:
62+
needs: [build]
63+
runs-on: ubuntu-latest
64+
steps:
65+
- name: Checkout
6366
uses: actions/checkout@v4
6467
with:
65-
repository: mosra/m.css
66-
path: docs/m.css
67-
68-
- name: Build Python docs
69-
working-directory: ${{ runner.workspace }}/manif/docs
70-
run: python m.css/documentation/python.py conf_python.py
71-
- name: Build C++ docs
72-
working-directory: ${{ runner.workspace }}/manif/docs
73-
run: |
74-
mkdir -p site/cpp
75-
python m.css/documentation/doxygen.py conf_cpp.py
76-
- name: Build site
77-
working-directory: ${{ runner.workspace }}/manif/docs
78-
run: python m.css/documentation/doxygen.py conf.py
68+
fetch-depth: 0
7969

80-
- name: Latex equation white color
81-
working-directory: ${{ runner.workspace }}/manif/docs
82-
run: ./fix_latex_color.sh
70+
- name: Set up Python
71+
uses: actions/setup-python@v5
72+
with:
73+
python-version: "3.12"
8374

84-
- name: Archive artifacts
85-
uses: actions/upload-artifact@v4
75+
- name: Update sources
76+
run: sudo apt-get update
77+
78+
- name: Install doc dependencies
79+
run: sudo apt-get install -y doxygen
80+
81+
# Those are necessary if pip doesn't find the wheels
82+
# and decides to rebuild from source
83+
- name: Install doc extra dependencies
84+
run: sudo apt-get install -y libjpeg-dev libxml2-dev libxslt1-dev
85+
86+
- name: Install manif dependencies
87+
run: sudo apt-get install -y libeigen3-dev
88+
89+
- name: linkcheck
90+
working-directory: docs
91+
run: make linkcheck
92+
93+
- uses: DavidAnson/markdownlint-cli2-action@v16
8694
with:
87-
name: site
88-
path: docs/site
95+
config: "docs/.sphinx/.markdownlint.json"
96+
97+
# documentation-checks:
98+
# uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
99+
# with:
100+
# working-directory: "docs"
101+
# fetch-depth: 0
102+
# install-target: "gh-ci-install"
89103

90104
deploy:
105+
needs: [test]
91106
runs-on: ubuntu-latest
92-
needs: [build]
93107
# todo: deploy if new tag/release
94108
if: |
95109
github.repository == 'artivis/manif' &&
96-
github.event_name == 'push' && github.ref == 'refs/heads/devel'
110+
github.event_name == 'push' &&
111+
github.ref == 'refs/heads/devel'
97112
steps:
98113
- name: Download artifacts
99114
uses: actions/download-artifact@v4
100115
with:
101-
name: site
102-
path: site
116+
name: doc
117+
path: doc
118+
103119
- name: Deploy
104120
uses: JamesIves/github-pages-deploy-action@v4
105121
with:
106122
branch: gh-pages
107-
folder: site
123+
folder: doc

0 commit comments

Comments
 (0)