Skip to content

Commit b378a1a

Browse files
AndBondStyleAndBondStyle
authored
Documentation Site (#45)
* First test * Use self-hosted runner * Fix site url * Drop readthedocs-related stuff * Update CI branches * Add versioning * Fix CI * Fix CI * Update CI * Update CI * Update home page * Add tikzjax demo * Remove caching * Add force arg * Update CI * Update CI * Update CI * Update CI * Update CI * Update CI * Update CI * Remove old CI, add readme badge
1 parent 3551992 commit b378a1a

File tree

12 files changed

+669
-217
lines changed

12 files changed

+669
-217
lines changed

‎.github/workflows/alt_ci.yml‎

Lines changed: 0 additions & 33 deletions
This file was deleted.

‎.github/workflows/ci.yml‎

Lines changed: 0 additions & 30 deletions
This file was deleted.

‎.github/workflows/docs.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: docs
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
- cart-pole-3 # TODO: Remove after merging to master
8+
9+
permissions:
10+
contents: write
11+
12+
jobs:
13+
deploy:
14+
runs-on: self-hosted
15+
steps:
16+
- uses: actions/checkout@v3
17+
with:
18+
fetch-depth: 0
19+
- uses: actions/setup-python@v4
20+
with:
21+
python-version: 3.9
22+
# TODO: Add proper chaching
23+
# TODO: Maybe use poetry-based action
24+
- run: pip install mkdocs-material mike poetry
25+
- run: |
26+
git config user.name github-actions
27+
git config user.email [email protected]
28+
- run: mike deploy --push --force --update-aliases $(poetry version -s) latest

‎docs/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Overview
2+
3+
Welcome to CartPole documentation

‎docs/js/mathjax.js‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// https://squidfunk.github.io/mkdocs-material/reference/math
2+
3+
window.MathJax = {
4+
tex: {
5+
inlineMath: [["\\(", "\\)"]],
6+
displayMath: [["\\[", "\\]"]],
7+
processEscapes: true,
8+
processEnvironments: true
9+
},
10+
options: {
11+
ignoreHtmlClass: ".*|",
12+
processHtmlClass: "arithmatex"
13+
}
14+
};
15+
16+
document$.subscribe(() => {MathJax.typesetPromise()})

docs/controller_protocol.md renamed to docs/protocol.md

Lines changed: 1 addition & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,4 @@
1-
# CartPole Controller Protocol
2-
3-
- [Overview](#overview)
4-
- [Variables](#variables)
5-
- [Config group](#config)
6-
- [State group](#state)
7-
- [Target group](#target)
8-
- [Error codes](#error-codes-enum)
9-
- [Commands](#commands)
10-
- [Get variable](#get-group-key1-key2-)
11-
- [Set variable](#set-group-key1val1-key2val2-)
12-
- [Reset](#reset)
1+
# Hardware Protocol
132

143
## Overview
154

docs/guide.md renamed to docs/quickstart.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1-
# Guide
1+
# Quickstart
22

33
## Enviroment
4+
45
Python is main language of project. So, students may learn control theory and make experiments faster and easier.
56

67
Firstly, you need checkout repo and prepare environemnt, using [poetry](https://python-poetry.org/docs).
@@ -58,7 +59,7 @@ for i in range(20):
5859
## Simulation
5960
For development and testing of control algorithms, we provide CartPole simulator, which fully implemntet CartPoleBase [interface](/cartpole/common/interface.py). The simulation is carried out by numerical integration of parameterized dynamic system (more information [here](/docs/cart_pole.pdf)). Also simulator may be used to train ML agents.
6061

61-
![CartPole](docs/svg/classic_cart_pole.svg)
62+
![CartPole](svg/linear_cart_pole.svg)
6263

6364
```python
6465
from cartpole import Error, State

‎docs/syntax-test.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# MkDocs & mkdocs-material syntax test
2+
3+
See [mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/) for more examples
4+
5+
## Callouts
6+
7+
!!! note "Important note"
8+
This is a note
9+
10+
!!! warning
11+
Uh oh
12+
13+
## Buttons
14+
15+
[Open Foxglove](http://foxglove.robotics-lab.ru/){ .md-button target="_blank" }
16+
17+
## Code
18+
19+
``` py title="main.py"
20+
import tensorflow as tf
21+
```
22+
23+
## Math ([mathjax](https://docs.mathjax.org/en/latest/))
24+
25+
We can use inline $m * a * t * h$ as well as blocks:
26+
27+
$$\begin{align}
28+
T_p & = T^t_p + T^r_p \nonumber \\
29+
& = \frac{1}{2} m_p \begin{Vmatrix}\dot{P}\end{Vmatrix}_2^2 + \frac{1}{2}I_p\dot{\theta}^2 \nonumber \\
30+
& = \frac{1}{2} m_p (\dot{x} + l \dot{\theta} \cos \theta )^2 + \frac{1}{2} m_p (l \dot{\theta} \sin \theta)^2 + \frac{1}{2}I_p\dot{\theta}^2 \nonumber \\
31+
& = \frac{1}{2} m_p \dot{x}^2 + m_p \dot{x} l \dot{\theta} \cos \theta + \frac{1}{2} \dot{\theta}^2 \left( m_p l^2 + I_p \right).
32+
\end{align}$$
33+
34+
## SVG ([tikzjax](https://github.com/kisonecat/tikzjax))
35+
36+
<script type="text/tikz">
37+
\begin{tikzpicture}[>=stealth]
38+
% world
39+
\draw[->, thick] (-1,3.1) -- (15,3.1) node[right] {\Large $x$};
40+
\draw[-, thick] (7,0.5) -- (7,5.7);
41+
42+
% hull
43+
\filldraw[red!100!black, fill=white, line width=5] (4.0,1.7) rectangle (10.0,4.5);
44+
45+
% y axis help
46+
\draw[-, dashed] (7,1.2) -- (7,5.0);
47+
48+
% stick
49+
\begin{scope}[rotate around={150:(7, 3.1)}]
50+
\filldraw[green!80!black, fill=green!80!black] (6.8, 3.4) rectangle (7.2, -6);
51+
52+
% C
53+
\node[circle, fill=blue, opacity=0.6, scale=0.5, label={above left:{\textcolor{blue}{$C$}}}] at (7, 3.1) {};
54+
55+
% P
56+
\node[circle, fill=blue, opacity=0.6, scale=0.5, label={above left:{\textcolor{blue}{$P$}}}] at (7, -1.3) {};
57+
58+
% l
59+
\draw[<->, thick, black] (7,3) -- (7, -1.2) node[midway,above] {\large $l$};
60+
\end{scope}
61+
62+
% f_x
63+
\draw[<-, thick, blue!70!black] (4.3,3.1) -- (6.9, 3.1) node[midway,above] {\large $f_x$};
64+
65+
% g
66+
\draw[->, thick, blue!70!black] (9.2, 6.81) -- (9.2, 5.2) node[midway,right] {\large $g$};
67+
68+
% \theta
69+
\draw[->, thick, orange!70!black] (7, 2.4) arc [start angle=-90, end angle=60, radius=0.7];
70+
\fill[->, opacity=0.2, orange!70!black] (7, 3.1) -- (7, 2.4) arc [start angle=-90, end angle=60, radius=0.7];
71+
\draw[thick, orange!70!black] (7.8, 2.8) node {\large $\theta$};
72+
73+
% m_C
74+
\draw[red!60!black] (5, 2.3) node {\large $m_c$};
75+
76+
% m_P
77+
\draw[green!40!black] (10.6, 10.5) node {\large $m_p$};
78+
79+
% formula
80+
% \draw (4,8) node[fill=yellow!30, draw, rounded corners] {\Large $\ddot{\theta} = -b\dot{\theta} -\frac{\ddot{x} \cos \theta + g \sin \theta}{k}$};
81+
% \draw (2,4) node[fill=yellow!30, draw, rounded corners] {\Large $\ddot{x} = u$};
82+
\end{tikzpicture}
83+
</script>
84+
85+
## Images
86+
87+
<figure markdown>
88+
![Image title](svg/linear_cart_pole.svg){ width="600" }
89+
<figcaption>Image caption</figcaption>
90+
</figure>
91+
92+
## Diagrams
93+
94+
``` mermaid
95+
sequenceDiagram
96+
autonumber
97+
Alice->>John: Hello John, how are you?
98+
loop Healthcheck
99+
John->>John: Fight against hypochondria
100+
end
101+
Note right of John: Rational thoughts!
102+
John-->>Alice: Great!
103+
John->>Bob: How about you?
104+
Bob-->>John: Jolly good!
105+
```

‎mkdocs.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
site_name: CartPole
2+
site_url: https://robotics-laboratory.github.io/cart-pole/
3+
repo_url: https://github.com/robotics-laboratory/cart-pole/
4+
repo_name: robotics-laboratory/cart-pole
5+
6+
nav:
7+
- Quickstart: quickstart.md
8+
- Syntax test: syntax-test.md
9+
- Hardware: protocol.md
10+
11+
theme:
12+
name: material
13+
palette:
14+
primary: deep orange
15+
features:
16+
- content.code.copy
17+
18+
extra:
19+
version:
20+
default: latest
21+
provider: mike
22+
23+
markdown_extensions:
24+
- admonition
25+
- pymdownx.details
26+
- md_in_html
27+
- attr_list
28+
- pymdownx.arithmatex:
29+
generic: true
30+
- pymdownx.emoji:
31+
emoji_index: !!python/name:materialx.emoji.twemoji
32+
emoji_generator: !!python/name:materialx.emoji.to_svg
33+
- pymdownx.superfences:
34+
custom_fences:
35+
- name: mermaid
36+
class: mermaid
37+
format: !!python/name:pymdownx.superfences.fence_code_format
38+
39+
extra_css:
40+
- https://tikzjax.com/v1/fonts.css
41+
42+
extra_javascript:
43+
- js/mathjax.js
44+
- https://polyfill.io/v3/polyfill.min.js?features=es6
45+
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
46+
- https://tikzjax.com/v1/tikzjax.js

0 commit comments

Comments
 (0)