Skip to content

Commit 05b1be9

Browse files
jhiddingjhidding
committed
more docs
1 parent 0e1dae6 commit 05b1be9

File tree

12 files changed

+505
-291
lines changed

12 files changed

+505
-291
lines changed

‎.entangled/filedb.json

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
{
2+
"version": "2.0.0-alpha-3",
3+
"files": [
4+
{
5+
"path": "README.md",
6+
"deps": null,
7+
"modified": "2023-05-20T15:45:38.374816",
8+
"hexdigest": "dead468bea87407e2e6a7b229e76c812a231e0f6289eddf171ba8bd0534e364c"
9+
},
10+
{
11+
"path": "docs/setup.md",
12+
"deps": null,
13+
"modified": "2023-05-20T22:27:47.967531",
14+
"hexdigest": "b011aa8d3e2046e683f453207e112b1fd47f67f6117b1f98fea4eb46da5d0549"
15+
},
16+
{
17+
"path": "examples/hello_world.py",
18+
"deps": [
19+
"docs/index.md"
20+
],
21+
"modified": "2023-05-20T15:50:49.652413",
22+
"hexdigest": "66e79b50c625e5edddbe3e1c1222b74ce0e5f776abc43ea6366816544219fc45"
23+
},
24+
{
25+
"path": "docs/index.md",
26+
"deps": null,
27+
"modified": "2023-05-20T22:25:25.108970",
28+
"hexdigest": "860d6dfc07cd8246a7fdb0c425eb6217677ef9006f84693c630b4faaf90bfcce"
29+
},
30+
{
31+
"path": "examples/plot.gp",
32+
"deps": [
33+
"docs/index.md"
34+
],
35+
"modified": "2023-05-20T22:13:50.926594",
36+
"hexdigest": "e0a44680408c7b2b7c4fec1551d0a6a835df6ecd0c1d68a758b43c2ef89ea29e"
37+
}
38+
],
39+
"source": [],
40+
"target": [
41+
"examples/plot.gp",
42+
"examples/hello_world.py"
43+
]
44+
}

‎test/test_ renamed to ‎.entangled/filedb.lock

File renamed without changes.

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ print("Hello, World!")
4949
that render like this:
5050
5151
``` {.python #hello-world}
52-
print("Hello, World!")
52+
print("Hello, Universe!")
5353
```
5454
5555
### Build Artifacts

‎docs/index.md

-1
This file was deleted.

‎docs/index.md

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Welcome to MkDocs Entangled Plugin
2+
Using this plugin, you can make your Entangled documents look better.
3+
4+
## Install
5+
6+
Install this with `pip install mkdocs-entangled-plugin`. To use the entangled plugin, add the following lines to your `mkdocs.yml`:
7+
8+
```yaml
9+
watch:
10+
- docs # watch markdown sources
11+
- src # add your src directories to watch
12+
13+
plugins:
14+
- entangled # this also runs `entangled sync` as a pre-build action
15+
16+
markdown_extensions:
17+
- pymdownx.superfences
18+
- pymdownx.tabbed:
19+
alternate_style: true
20+
```
21+
22+
Also create `entangled.toml`, the `version` field is obligatory.
23+
24+
```toml
25+
version = "2.0"
26+
watch_list = ["docs/**/*.md"]
27+
hooks = ["build"]
28+
```
29+
30+
## Components
31+
This plugin bundles functionality for literate programming with Entangled.
32+
33+
- Annotate code blocks with titles.
34+
- Run entangled as part of `mkdocs serve` cycle
35+
36+
### Annotate code blocks
37+
The default markdown syntax that Entangled supports has fenced code blocks as follows
38+
39+
~~~markdown
40+
``` {.python file=examples/hello_world.py}
41+
if __name__ == "__main__":
42+
<<hello-world>>
43+
```
44+
~~~
45+
46+
Which renders like this:
47+
48+
``` {.python file=examples/hello_world.py}
49+
if __name__ == "__main__":
50+
<<hello-world>>
51+
```
52+
53+
Or named code blocks
54+
55+
~~~markdown
56+
``` {.python #hello-world}
57+
print("Hello, World!")
58+
```
59+
~~~
60+
61+
that render like this:
62+
63+
``` {.python #hello-world}
64+
print("Hello, World!")
65+
```
66+
67+
### Build Artifacts
68+
69+
Build artifacts by specifying a Makefile.
70+
71+
~~~markdown
72+
=== "Figure 1"
73+
74+
![](fig/plot.svg)
75+
76+
=== "Source"
77+
78+
``` {.gnuplot file=examples/plot.gp}
79+
# enter your plotting commands here
80+
```
81+
82+
``` {.make #build target=docs/fig/plot.svg}
83+
docs/fig/plot.svg: examples/plot.gp
84+
> mkdir -p $(@D)
85+
> gnuplot $^ > $@
86+
```
87+
~~~
88+
89+
=== "Figure 1"
90+
91+
![](fig/plot.svg)
92+
93+
=== "Source"
94+
95+
``` {.gnuplot file=examples/plot.gp}
96+
set term svg background rgb 'white' size 700, 500
97+
sinc(r) = sin(pi*r) / (pi*r)
98+
set isosamples 50, 50
99+
set hidden3d
100+
set xrange [-4:4]
101+
set yrange [-4:4]
102+
set xyplane 0
103+
set title "Sinc function"
104+
splot sinc(sqrt(x**2 + y**2)) t'' lc rgb '#5533cc'
105+
```
106+
107+
``` {.make #build target=docs/fig/plot.svg}
108+
docs/fig/plot.svg: examples/plot.gp
109+
> mkdir -p $(@D)
110+
> gnuplot $^ > $@
111+
```
112+
113+
## License
114+
Licensed under the Apache-2 license agreement: see LICENSE

‎docs/setup.md

+38-33
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ You may want to setup a virtual environment to install MkDocs into. Even if your
1515
```sh
1616
poetry init
1717
# <<follow the gentle instructions>>
18-
poetry add -D mkdocs mkdocs-material mkdocs-entangled-plugin
18+
poetry add -D mkdocs mkdocs-material entangled-cli[rich] mkdocs-entangled-plugin
1919
poetry shell
2020
```
2121

@@ -54,43 +54,24 @@ mkdocs serve
5454
This will start a build loop and web server. That means that every time one of the source files change, MkDocs will compile the Markdown to HTML and the browser will automatically refresh.
5555

5656
## Setup Entangled
57-
If you haven't yet installed Entangled, follow the instructions here, otherwise continue.
57+
Entangled will work without any additional configuration in `entangled.toml`. The default config monitors the entire source repository for Markdown files. Files that are extracted from the Markdown are also watched for changes. If you'd like to limit the scope of Markdown files that are monitored, you can set `watch_list` to a list of glob patterns. For MkDocs projects it makes sense to set `watch_list = [ "docs/**/*.md" ]`.
5858

59-
<details markdown="block">
60-
<summary>Howto install Entangled</summary>
61-
Entangled needs the Glasgow Haskell Compiler to build. The best way to install GHC is through [GHCUp](https://www.haskell.org/ghcup/). Then, run the following commands:
59+
To enable building artifacts add the `build` hook, by setting `hooks = ["build"]`.
6260

63-
```sh
64-
git clone https://github.com/entangled/entangled.git
65-
cd entangled
66-
cabal build
67-
cabal install
68-
```
69-
</details>
70-
71-
Make sure to go to your awesome project folder (remember, the MkDocs build-and-serve loop is still running in your other terminal).
72-
To setup Entangled, start with an initial config
73-
74-
```sh
75-
entangled config -m > entangled.dhall
76-
```
77-
78-
Then, edit these settings to look like this.
61+
The complete configuration then looks like this:
7962

80-
```dhall
81-
let entangled = https://raw.githubusercontent.com/entangled/entangled/v1.2.2/data/config-schema.dhall
82-
sha256:9bb4c5649869175ad0b662d292fd81a3d5d9ccb503b1c7e316d531b7856fb096
83-
84-
in { entangled = entangled.Config ::
85-
{ watchList = [ "docs/*.md" ] : List Text
86-
}
87-
}
63+
``` {.toml file=examples/entangled.toml}
64+
version = "2.0"
65+
watch_list = ["docs/**/*.md"]
66+
hooks = ["build"]
8867
```
8968

90-
Run the Entangled daemon.
69+
Entangled runs as a pre-build action in MkDocs. So, you may want to add your generated source files in the watch list of MkDocs. Assuming your source files are in `./src`:
9170

92-
```sh
93-
entangled daemon
71+
```yaml
72+
watch:
73+
- docs
74+
- src
9475
```
9576

9677
## Extras
@@ -125,6 +106,26 @@ extra_javascript:
125106

126107
You'll also need to create `docs/js/mathjax.jl`.
127108

109+
```js
110+
window.MathJax = {
111+
tex: {
112+
inlineMath: [["\\(", "\\)"]],
113+
displayMath: [["\\[", "\\]"]],
114+
processEscapes: true,
115+
processEnvironments: true,
116+
tags: 'ams'
117+
},
118+
options: {
119+
ignoreHtmlClass: ".*|",
120+
processHtmlClass: "arithmatex"
121+
}
122+
};
123+
124+
document$.subscribe(() => {
125+
MathJax.typesetPromise();
126+
})
127+
```
128+
128129
### Dark mode
129130
You can enable a dark-mode toggle by adding to your `mkdocs.yml`
130131

@@ -145,9 +146,11 @@ theme:
145146
name: Switch to light mode
146147
```
147148

148-
## Github Actions
149+
### Github Actions
149150
You may want to use Github Actions to deploy the website. I use the following `.github/workflows/deploy-pages.yaml`:
150151

152+
<details><summary>Deploy Pages action</summary>
153+
151154
```yaml
152155
name: Deploy Pages
153156
@@ -197,6 +200,8 @@ jobs:
197200
uses: actions/deploy-pages@v2
198201
```
199202

203+
</details>
204+
200205
## Commit
201206
Don't forget to create a `README.md`, `LICENSE`, and later on a `CITATION.cff`. You may want to add `poetry.lock` to `.gitignore`.
202207
You should be good to go! A fresh Entangled/MkDocs project should have the following files:

‎entangled.dhall

-8
This file was deleted.

‎entangled.toml

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
version = "2.0"
2+
watch_list = ["docs/**/*.md"]
3+
hooks = ["build"]

‎examples/hello_world.py

+4-17
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,6 @@
1-
# ~\~ language=Python filename=examples/hello_world.py
2-
# ~\~ begin <<README.md|examples/hello_world.py>>[init]
1+
# ~/~ begin <<docs/index.md#examples/hello_world.py>>[init]
32
if __name__ == "__main__":
4-
# ~\~ begin <<README.md|hello-world>>[init]
3+
# ~/~ begin <<docs/index.md#hello-world>>[init]
54
print("Hello, World!")
6-
# ~\~ end
7-
# ~\~ begin <<README.md|hello-world>>[1]
8-
print("Hello, World!")
9-
# ~\~ end
10-
# ~\~ end
11-
# ~\~ begin <<README.md|examples/hello_world.py>>[1]
12-
if __name__ == "__main__":
13-
# ~\~ begin <<README.md|hello-world>>[init]
14-
print("Hello, World!")
15-
# ~\~ end
16-
# ~\~ begin <<README.md|hello-world>>[1]
17-
print("Hello, World!")
18-
# ~\~ end
19-
# ~\~ end
5+
# ~/~ end
6+
# ~/~ end

‎examples/plot.gp

+11-15
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,11 @@
1-
# ~\~ language=Gnuplot filename=examples/plot.gp
2-
# ~\~ begin <<README.md|examples/plot.gp>>[init]
3-
# enter your plotting commands here
4-
# ~\~ end
5-
# ~\~ begin <<README.md|examples/plot.gp>>[1]
6-
set term svg background rgb 'white' size 700, 500
7-
sinc(r) = sin(pi*r) / (pi*r)
8-
set isosamples 50, 50
9-
set hidden3d
10-
set xrange [-4:4]
11-
set yrange [-4:4]
12-
set xyplane 0
13-
set title "Sinc function"
14-
splot sinc(sqrt(x**2 + y**2)) t'' lc rgb '#5533cc'
15-
# ~\~ end
1+
# ~/~ begin <<docs/index.md#examples/plot.gp>>[init]
2+
set term svg background rgb 'white' size 700, 500
3+
sinc(r) = sin(pi*r) / (pi*r)
4+
set isosamples 50, 50
5+
set hidden3d
6+
set xrange [-4:4]
7+
set yrange [-4:4]
8+
set xyplane 0
9+
set title "Sinc function"
10+
splot sinc(sqrt(x**2 + y**2)) t'' lc rgb '#5533cc'
11+
# ~/~ end

‎mkdocs_entangled/plugin.py

+3-2
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,16 @@
55
from mkdocs.structure.files import Files
66

77
from entangled.commands import sync
8+
from entangled.main import configure
89

910
from .on_page_markdown import on_page_markdown
1011
from .config import EntangledConfig
1112

1213
class EntangledPlugin(mkdocs.plugins.BasePlugin[EntangledConfig]):
1314
def on_pre_build(self, config: MkDocsConfig):
14-
logging.info("Running entangled sync()")
15+
configure()
16+
logging.info("Running `entangled sync`")
1517
sync()
1618

1719
def on_page_markdown(self, markdown: str, *, page: Page, config: MkDocsConfig, files: Files):
18-
logging.info("Entangled markdown filter version 0.3.0")
1920
return on_page_markdown(markdown, page=page, config=config, files=files)

0 commit comments

Comments
 (0)