Skip to content

Commit 25cda91

Browse files
jhiddingjhidding
committed
add setup instructions
1 parent a537ef1 commit 25cda91

File tree

5 files changed

+260
-3
lines changed

5 files changed

+260
-3
lines changed

‎README.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -21,19 +21,19 @@ This plugin bundles functionality for literate programming with Entangled.
2121
- Annotate code blocks with titles.
2222
- Build artifacts using Make.
2323
24-
### Annotates code blocks
24+
### Annotate code blocks
2525
The default markdown syntax that Entangled supports has fenced code blocks as follows
2626
2727
~~~markdown
28-
``` {.python file=hello_world.py}
28+
``` {.python file=examples/hello_world.py}
2929
if __name__ == "__main__":
3030
<<hello-world>>
3131
```
3232
~~~
3333
3434
Which renders like this:
3535
36-
``` {.python file=hello_world.py}
36+
``` {.python file=examples/hello_world.py}
3737
if __name__ == "__main__":
3838
<<hello-world>>
3939
```

‎docs/setup.md

+225
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# Setup instructions for MkDocs with Entangled
2+
If you'd like to use Entangled together with MkDocs, here's an opiniated guide (if you have differing opinions, you'll know howto adapt).
3+
4+
## Python and MkDocs
5+
Start with an empty project folder, say `my-awesome-project`.
6+
7+
```sh
8+
mkdir my_awesome_project
9+
cd my_awesome_project
10+
git init
11+
```
12+
13+
You may want to setup a virtual environment to install MkDocs into. Even if your project is not Python related, it pays to have a reproducible build environment for your documentation. I use [Poetry](https://python-poetry.org/) to manage my environments.
14+
15+
```sh
16+
poetry init
17+
# <<follow the gentle instructions>>
18+
poetry add -D mkdocs mkdocs-material mkdocs-entangled-plugin
19+
poetry shell
20+
```
21+
22+
Using virtual environments will take up some disk space. With these moderate requirements however, we're still under 200 MB.
23+
24+
Next we initialize, configure, and run MkDocs.
25+
26+
```sh
27+
mkdocs new .
28+
```
29+
30+
Now edit `mkdocs.yml` to your own settings, here's an example.
31+
32+
```yaml
33+
site_name: My Awesome Project
34+
site_url: https://joeplummer.github.io/my-awesome-project
35+
repo_url: https://github.com/joeplummer/my-awesome-project
36+
37+
plugins:
38+
- entangled
39+
40+
markdown_extensions:
41+
- pymdownx.superfences
42+
43+
theme:
44+
name: material
45+
```
46+
47+
This sets the title, repo name and a toggle for dark mode viewing. the `entangled` plugin needs `pymdownx.superfences` to be enabled.
48+
Make sure to check out [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) for more documentation on configuring MkDocs with Material.
49+
50+
```sh
51+
mkdocs serve
52+
```
53+
54+
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.
55+
56+
## Setup Entangled
57+
If you haven't yet installed Entangled, follow the instructions here, otherwise continue.
58+
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:
62+
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.
79+
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+
}
88+
```
89+
90+
Run the Entangled daemon.
91+
92+
```sh
93+
entangled daemon
94+
```
95+
96+
## Extras
97+
### Syntax Highlighting
98+
Add the following to the `markdown_extensions` section in `mkdocs.yml`:
99+
100+
```yaml
101+
markdown_extensions:
102+
# <<your old settings are still here>>
103+
# ...
104+
- pymdownx.highlight:
105+
anchor_linenums: true
106+
line_spans: __span
107+
pygments_lang_class: true
108+
```
109+
110+
### Equations using Mathjax
111+
A common requirement is to have support for equations. Add the following to your `mkdocs.yml`
112+
113+
```yaml
114+
markdown_extensions:
115+
# <<your old settings are still here>>
116+
# ...
117+
- pymdownx.arithmatex:
118+
generic: true
119+
120+
extra_javascript:
121+
- js/mathjax.js
122+
- https://polyfill.io/v3/polyfill.min.js?features=es6
123+
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
124+
```
125+
126+
You'll also need to create `docs/js/mathjax.jl`.
127+
128+
### Dark mode
129+
You can enable a dark-mode toggle by adding to your `mkdocs.yml`
130+
131+
```yaml
132+
theme:
133+
name: material
134+
palette:
135+
# Palette toggle for light mode
136+
- scheme: default
137+
toggle:
138+
icon: material/brightness-7
139+
name: Switch to dark mode
140+
141+
# Palette toggle for dark mode
142+
- scheme: slate
143+
toggle:
144+
icon: material/brightness-4
145+
name: Switch to light mode
146+
```
147+
148+
## Github Actions
149+
You may want to use Github Actions to deploy the website. I use the following `.github/workflows/deploy-pages.yaml`:
150+
151+
```yaml
152+
name: Deploy Pages
153+
154+
# Controls when the workflow will run
155+
on:
156+
# Triggers the workflow on push or pull request events but only for the "main" branch
157+
push:
158+
branches: [ "main" ]
159+
160+
# Allows you to run this workflow manually from the Actions tab
161+
workflow_dispatch:
162+
163+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
164+
permissions:
165+
contents: read
166+
pages: write
167+
id-token: write
168+
169+
jobs:
170+
build:
171+
environment:
172+
name: github-pages
173+
url: ${{ steps.deployment.outputs.page_url }}
174+
# The type of runner that the job will run on
175+
runs-on: ubuntu-latest
176+
177+
# Steps represent a sequence of tasks that will be executed as part of the job
178+
steps:
179+
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
180+
- uses: actions/checkout@v3
181+
182+
- name: Install
183+
run: |
184+
pip install poetry
185+
poetry install
186+
187+
- name: Generate site
188+
run: poetry run mkdocs build
189+
190+
- name: Upload artifact
191+
uses: actions/upload-pages-artifact@v1
192+
with:
193+
path: 'site'
194+
195+
- name: Deploy to GitHub Pages
196+
id: deployment
197+
uses: actions/deploy-pages@v2
198+
```
199+
200+
## Commit
201+
Don't forget to create a `README.md`, `LICENSE`, and later on a `CITATION.cff`. You may want to add `poetry.lock` to `.gitignore`.
202+
You should be good to go! A fresh Entangled/MkDocs project should have the following files:
203+
204+
```
205+
.
206+
├── CITATION.cff
207+
├── docs
208+
│   ├── index.md
209+
│   └── js
210+
│   └── mathjax.js
211+
├── entangled.dhall
212+
├── LICENSE
213+
├── mkdocs.yml
214+
├── pyproject.toml
215+
└── README.md
216+
```
217+
218+
Create a home for your new project and push.
219+
220+
```sh
221+
git add .
222+
git commit -m 'initial commit'
223+
git remote add origin [email protected]:joeplummer/my-awesome-project.git
224+
git push -u origin main
225+
```

‎entangled.dhall

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
let entangled = https://raw.githubusercontent.com/entangled/entangled/v1.2.2/data/config-schema.dhall
2+
sha256:9bb4c5649869175ad0b662d292fd81a3d5d9ccb503b1c7e316d531b7856fb096
3+
4+
in { entangled = entangled.Config ::
5+
{ watchList = [ "README.md" ] : List Text
6+
}
7+
}
8+

‎examples/hello_world.py

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# ~\~ language=Python filename=examples/hello_world.py
2+
# ~\~ begin <<README.md|examples/hello_world.py>>[init]
3+
if __name__ == "__main__":
4+
# ~\~ begin <<README.md|hello-world>>[init]
5+
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

‎mkdocs.yml

+5
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,13 @@ plugins:
77

88
markdown_extensions:
99
- pymdownx.superfences
10+
- pymdownx.extra
1011
- pymdownx.tabbed:
1112
alternate_style: true
13+
- pymdownx.highlight:
14+
anchor_linenums: true
15+
line_spans: __span
16+
pygments_lang_class: true
1217

1318
theme:
1419
name: material

0 commit comments

Comments
 (0)