8000 docs: 🚧 mkdoc serve error · ttngu207/datajoint-python@b5a0985 · GitHub
[go: up one dir, main page]
Skip to content

Commit b5a0985

Browse files
author
Drew Yang
committed
docs: 🚧 mkdoc serve error
1 parent 275e0d7 commit b5a0985

File tree

8 files changed

+115
-42
lines changed

8 files changed

+115
-42
lines changed

‎docs/.docker/Dockerfile

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

‎docs/.docker/apk_requirements.txt

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

‎docs/.markdownlint.yaml

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
11
# https://github.com/DavidAnson/markdownlint
22
# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
3+
MD007: false # Unordered list indentation
34
MD009: false # permit trailing spaces
45
MD013:
5-
line_length: "88" # Line length limits
6+
# previously we defined line_length to 88 which is better for python
7+
# but not for markdown
8+
line_length:
9+
- strict: false
610
tables: false # disable for tables
711
headings: false # disable for headings
8-
code_blocks: false # disable for code blocks
12+
MD029: false # Ordered list item prefix
913
MD030: false # Number of spaces after a list
14+
MD032: false # Lists should be surrounded by blank lines
1015
MD033: # HTML elements allowed
1116
allowed_elements:
1217
- "div"

‎docs/Dockerfile

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
FROM python:3-alpine
2+
3+
WORKDIR /main
4+
COPY mkdocs.yaml mkdocs.yaml
5+
COPY src/ src/
6+
COPY pip_requirements.txt pip_requirements.txt
7+
8+
ARG BOT_PAT
9+
RUN \
10+
apk add --no-cache git && \
11+
pip install --no-cache-dir -r /main/pip_requirements.txt
12+
#&& \
13+
#pip install --no-cache git+https://${BOT_PAT}@github.com/datajoint/mkdocs-material-insiders.git@master

‎docs/README.md

Lines changed: 82 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,92 @@
1-
# Docs Contributions
1+
# Contribute to DataJoint Documentation
22

3-
Docs contributors should be aware of the following extensions, with the corresponding
4-
settings files, that were used in developing these docs:
3+
This is the home for DataJoint software documentation as hosted at https://datajoint.com/docs/core/datajoint-python/latest/
54

6-
- [MarkdownLinter](https://github.com/DavidAnson/markdownlint):
5+
## VSCode Linter Extensions and Settings
6+
7+
The following extensions were used in developing these docs, with the corresponding
8+
settings files:
9+
10+
- Recommended extensions are already specified in `.vscode/extensions.json`, it will ask you to install them when you open the project if you haven't installed them.
11+
- settings in `.vscode/settings.json`
12+
- [MarkdownLinter](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint):
713
- `.markdownlint.yaml` establishes settings for various
814
[linter rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)
915
- `.vscode/settings.json` formatting on save to fix linting
1016

11-
- [CSpell](https://github.com/streetsidesoftware/vscode-spell-checker): `cspell.json`
17+
- [CSpell](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker): `cspell.json`
1218
has various ignored words.
1319

14-
- [ReWrap](https://github.com/stkb/Rewrap/): `.vscode/settings.json` allows toggling
20+
- [ReWrap](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap): `.vscode/settings.json` allows toggling
1521
automated hard wrapping for files at 88 characters. This can also be keymapped to be
1622
performed on individual paragraphs, see documentation.
23+
24+
## With Virtual Environment
25+
26+
conda
27+
```bash
28+
conda create -n djdocs -y
29+
conda activate djdocs
30+
```
31+
venv
32+
```bash
33+
python -m venv .venv
34+
source .venv/bin/activate
35+
```
36+
37+
Then install the required packages:
38+
```bash
39+
pip install -r pip_requirements.txt
40+
```
41+
42+
Run mkdocs at: http://127.0.0.1:8000/docs/
43+
```bash
44+
# It will automatically reload the docs when changes are made
45+
mkdocs serve --config-file ./mkdocs.yaml
46+
```
47+
48+
## With Docker
49+
50+
> We mostly use Docker to simplify docs deployment
51+
52 A3DB +
Ensure you have `Docker` and `Docker Compose` installed.
53+
54+
Then run the following:
55+
```bash
56+
# It will automatically reload the docs when changes are made
57+
MODE="LIVE" docker compose up --build
58+
```
59+
60+
Navigate to http://127.0.0.1:8000/docs/ to preview the changes.
61+
62+
This setup supports live-reloading so all that is needed is to save the markdown files
63+
and/or `mkdocs.yaml` file to trigger a reload.
64+
65+
## Mkdocs Warning Explanation
66+
67+
> TL;DR: We need to do it this way for hosting, please keep it as is.
68+
69+
```log
70+
WARNING - A reference to 'core/datajoint-python/' is included in the 'nav' configuration, which is not found
71+
in the documentation files.
72+
INFO - Doc file 'index.md' contains an unrecognized relative link './core/datajoint-python/', it was left
73+
as is.
74+
```
75+
76+
- We use reverse proxy to proxy our docs sites, here is the proxy flow:
77+
- You hit `datajoint.com/*` on your browser
78+
- It'll bring you to the reverse proxy server first, that you wouldn't notice
79+
- when your URL ends with:
80+
- `/` is the company page
81+
- `/docs/` is the landing/navigation page hosted by datajoint/datajoint-docs's github pages
82+
- `/docs/core/datajoint-python/` is the actual docs site hosted by datajoint/datajoint-python's github pages
83+
- `/docs/elements/element-*/` is the actual docs site hosted by each element's github pages
84+
85+
86+
```log
87+
WARNING - Doc file 'partnerships/openephysgui.md' contains a link
88+
'../../images/community-partnerships-openephysgui-logo.png', but the target
89+
'../images/community-partnerships-openephysgui-logo.png' is not found among documentation files.
90+
Did you mean '../images/community-partnerships-openephysgui-logo.png'?
91+
```
92+
- We use Github Pages to host our docs, the image references needs to follow the mkdocs's build directory structure, under `site/` directory once you run mkdocs.

‎docs/docker-compose.yaml

Lines changed: 10 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,31 @@
1-
# MODE="LIVE|QA|BUILD" PACKAGE=datajoint UPSTREAM_REPO=https://github.com/datajoint/datajoint-python.git HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
2-
version: "2.4"
1+
# MODE="LIVE|QA|BUILD" LATEST_TAG=$(git describe --tags --abbrev=0) docker compose up --build
32
services:
43
docs:
54
build:
6-
dockerfile: docs/.docker/Dockerfile
7-
context: ../
8-
args:
9-
- PACKAGE
10-
image: ${PACKAGE}_python-docs
5+
context: .
6+
dockerfile: Dockerfile
7+
image: datajoint-python-docs
118
environment:
12-
- PACKAGE
13-
- UPSTREAM_REPO
149
- MODE
10+
- LATEST_TAG
1511
volumes:
1612
- ..:/main
17-
user: ${HOST_UID}:anaconda
1813
ports:
19-
- 80:80
14+
- 8000:8000
2015
command:
2116
- sh
2217
- -c
2318
- |
2419
set -e
2520
if echo "$${MODE}" | grep -i live &>/dev/null; then
26-
mkdocs serve --config-file ./docs/mkdocs.yaml -a 0.0.0.0:80
21+
mkdocs serve --config-file mkdocs.yaml -a 0.0.0.0:8000
2722
elif echo "$${MODE}" | grep -iE "qa|build" &>/dev/null; then
2823
git branch -D gh-pages || true
2924
git fetch $${UPSTREAM_REPO} gh-pages:gh-pages || true
30-
mike deploy --config-file ./docs/mkdocs.yaml -u $$(grep -oE '\d+\.\d+' /main/$${PACKAGE}/version.py) latest
31-
mike set-default --config-file ./docs/mkdocs.yaml latest
25+
mike deploy --config-file mkdocs.yaml -u $$LATEST_TAG latest
26+
mike set-default --config-file mkdocs.yaml latest
3227
if echo "$${MODE}" | grep -i qa &>/dev/null; then
33-
mike serve --config-file ./docs/mkdocs.yaml -a 0.0.0.0:80
28+
mike serve --config-file mkdocs.yaml -a 0.0.0.0:8000
3429
fi
3530
else
3631
echo "Unexpected mode..."

‎docs/mkdocs.yaml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -139,8 +139,8 @@ markdown_extensions:
139139
- toc:
140140
permalink: true
141141
- pymdownx.emoji:
142-
emoji_index: !!python/name:materialx.emoji.twemoji
143-
emoji_generator: !!python/name:materialx.emoji.to_svg
142+
emoji_index: !!python/name:material.extensions.emoji.twemoji
143+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
144144
options:
145145
custom_icons:
146146
- .overrides/.icons

‎docs/.docker/pip_requirements.txt renamed to ‎docs/pip_requirements.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
mkdocs-material==9.1.17
1+
mkdocs-material
22
mkdocs-redirects
33
mkdocstrings
44
mkdocstrings-python

0 commit comments

Comments
 (0)
0