10000 fix: 🐛 update mkdocs · ttngu207/datajoint-python@f50c82c · GitHub
[go: up one dir, main page]
Skip to content

Commit f50c82c

Browse files
author
Drew Yang
committed
< 10000 div class="CommitHeader-module__commit-message-container--nl1pf">
fix: 🐛 update mkdocs
1 parent b5a0985 commit f50c82c

File tree

7 files changed

+91
-60
lines changed

7 files changed

+91
-60
lines changed

‎.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ venv.bak/
144144
.ropeproject
145145

146146
# mkdocs documentation
147-
/site
147+
/docs/site
148148

149149
# mypy
150150
.mypy_cache/

‎docs/Dockerfile

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,16 @@
1-
FROM python:3-alpine
1+
FROM python:3
22

33
WORKDIR /main
4-
COPY mkdocs.yaml mkdocs.yaml
5-
COPY src/ src/
6-
COPY pip_requirements.txt pip_requirements.txt
4+
COPY ./docs/pip_requirements.txt /main/docs/pip_requirements.txt
5+
COPY ./datajoint /main/datajoint/
6+
COPY ./pyproject.toml /main/pyproject.toml
77

8-
ARG BOT_PAT
98
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
9+
# Install docs dependencies
10+
pip install --no-cache-dir -r /main/docs/pip_requirements.txt && \
11+
# Install datajoint
12+
pip install --no-cache-dir -e /main/
13+
14+
# Install dependencies first and use docker cache
15+
# modify docs content won't cause image rebuild
16+
COPY ./docs/ /main/docs/

‎docs/README.md

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -36,13 +36,22 @@ source .venv/bin/activate
3636

3737
Then install the required packages:
3838
```bash
39-
pip install -r pip_requirements.txt
39+
# go to the repo's root directory to generate API docs
40+
# cd ~/datajoint-python/
41+
42+
# install mkdocs related requirements
43+
pip install -r ./docs/pip_requirements.txt
44+
# install datajoint, since API docs are generated from the package
45+
pip install -e .[dev]
4046
```
4147

42-
Run mkdocs at: http://127.0.0.1:8000/docs/
48+
Run mkdocs at: http://127.0.0.1:8000/
4349
```bash
50+
# go to the repo's root directory to generate API docs
51+
# cd ~/datajoint-python/
52+
4453
# It will automatically reload the docs when changes are made
45-
mkdocs serve --config-file ./mkdocs.yaml
54+
mkdocs serve --config-file ./docs/mkdocs.yaml
4655
```
4756

4857
## With Docker
@@ -57,7 +66,7 @@ Then run the following:
5766
MODE="LIVE" docker compose up --build
5867
```
5968

60-
Navigate to http://127.0.0.1:8000/docs/ to preview the changes.
69+
Navigate to http://127.0.0.1:8000/ to preview the changes.
6170

6271
This setup supports live-reloading so all that is needed is to save the markdown files
6372
and/or `mkdocs.yaml` file to trigger a reload.
@@ -67,10 +76,8 @@ and/or `mkdocs.yaml` file to trigger a reload.
6776
> TL;DR: We need to do it this way for hosting, please keep it as is.
6877
6978
```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.
79+
INFO - Doc file 'index.md' contains an unrecognized relative link './develop', it was left as is. Did you mean
80+
'develop.md'?
7481
```
7582

7683
- We use reverse proxy to proxy our docs sites, here is the proxy flow:
@@ -84,9 +91,7 @@ INFO - Doc file 'index.md' contains an unrecognized relative link './core/da
8491

8592

8693
```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'?
94+
WARNING - Doc file 'query/operators.md' contains a link '../../../images/concepts-operators-restriction.png', but
95+
the target '../../images/concepts-operators-restriction.png' is not found among documentation files.
9196
```
9297
- 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: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,34 @@
1-
# MODE="LIVE|QA|BUILD" LATEST_TAG=$(git describe --tags --abbrev=0) docker compose up --build
1+
# MODE="LIVE|QA|BUILD" PACKAGE=datajoint UPSTREAM_REPO=https://github.com/datajoint/datajoint-python.git docker compose up --build
22
services:
33
docs:
44
build:
5-
context: .
6-
dockerfile: Dockerfile
5+
# some docs need to be dynamically generated from the datajoint PACKAGE
6+
context: ..
7+
dockerfile: docs/Dockerfile
78
image: datajoint-python-docs
89
environment:
9-
- MODE
10-
- LATEST_TAG
10+
MODE: ${MODE:-LIVE} # specify mode: LIVE, QA, BUILD
11+
# specify package to generate API docs
12+
PACKAGE: ${PACKAGE:-datajoint}
13+
UPSTREAM_REPO: ${UPSTREAM_REPO:-https://github.com/datajoint/datajoint-python.git}
1114
volumes:
1215
- ..:/main
1316
ports:
1417
- 8000:8000
1518
command:
16-
- sh
19+
- bash
1720
- -c
1821
- |
1922
set -e
2023
if echo "$${MODE}" | grep -i live &>/dev/null; then
21-
mkdocs serve --config-file mkdocs.yaml -a 0.0.0.0:8000
24+
mkdocs serve --config-file /main/docs/mkdocs.yaml -a 0.0.0.0:8000
2225
elif echo "$${MODE}" | grep -iE "qa|build" &>/dev/null; then
2326
git branch -D gh-pages || true
2427
git fetch $${UPSTREAM_REPO} gh-pages:gh-pages || true
25-
mike deploy --config-file mkdocs.yaml -u $$LATEST_TAG latest
26-
mike set-default --config-file mkdocs.yaml latest
28+
mike deploy --ignore-remote-status --config-file /main/docs/mkdocs.yaml -u $$(grep -oE '\d+\.\d+' /main/$${PACKAGE}/version.py) latest
29+
# mike set-default --config-file /main/docs/mkdocs.yaml latest
2730
if echo "$${MODE}" | grep -i qa &>/dev/null; then
28-
mike serve --config-file mkdocs.yaml -a 0.0.0.0:8000
31+
mike serve --config-file /main/docs/mkdocs.yaml -a 0.0.0.0:8000
2932
fi
3033
else
3134
echo "Unexpected mode..."

‎docs/src/.overrides/partials/nav.html

Lines changed: 46 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,53 @@
1+
<!-- Reference from: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/nav.html -->
2+
3+
{% import "partials/nav-item.html" as item with context %}
4+
5+
<!-- Determine classes -->
16
{% set class = "md-nav md-nav--primary" %}
27
{% if "navigation.tabs" in features %}
3-
{% set class = class ~ " md-nav--lifted" %}
8+
{% set class = class ~ " md-nav--lifted" %}
49
{% endif %}
510
{% if "toc.integrate" in features %}
6-
{% set class = class ~ " md-nav--integrated" %}
11+
{% set class = class ~ " md-nav--integrated" %}
712
{% endif %}
8-
<nav class="{{ class }}" aria-label="{{ lang.t('nav.title') }}" data-md-level="0">
9-
<label class="md-nav__title" for="__drawer">
10-
<a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" title="{{ config.site_name | e }}"
11-
class="md-nav__button md-logo" aria-label="{{ config.site_name }}" data-md-component="logo">
12-
{% include "partials/logo.html" %}
13-
</a>
14-
{#-
15-
Add DataJoint home link to navigation header, otherwise unchanged
16-
-#}
17-
<a href="https://datajoint.com/docs/" title="DataJoint">
18-
⬅ Home
19-
</a>
20-
</label>
21-
{% if config.repo_url %}
13+
14+
<!-- Navigation -->
15+
<nav
16+
class="{{ class }}"
17+
aria-label="{{ lang.t('nav') }}"
18+
data-md-level="0"
19+
>
20+
21+
<!-- Site title -->
22+
<label class="md-nav__title" for="__drawer">
23+
<a
24+
href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"
25+
title="{{ config.site_name | e }}"
26+
class="md-nav__button md-logo"
27+
aria-label="{{ config.site_name }}"
28+
data-md-component="logo"
29+
>
30+
{% include "partials/logo.html" %}
31+
</a>
32+
<!-- Add DataJoint home link to navigation header, otherwise unchanged -->
33+
<!-- {{ config.site_name }} -->
34+
<a href="https://datajoint.com/docs/" title="DataJoint">
35+
⬅ Home
36+
</a>
37+
</label>
38+
39+
<!-- Repository information -->
40+
{% if config.repo_url %}
2241
<div class="md-nav__source">
23-
{% include "partials/source.html" %}
42+
{% include "partials/source.html" %}
2443
</div>
25-
{% endif %}
26-
<ul class="md-nav__list" data-md-scrollfix>
27-
{% for nav_item in nav %}
28-
{% set path = "__nav_" ~ loop.index %}
29-
{% set level = 1 %}
30-
{% include "partials/nav-item.html" %}
31-
{% endfor %}
32-
</ul>
33-
</nav>
44+
{% endif %}
45+
46+
<!-- Navigation list -->
47+
<ul class="md-nav__list" data-md-scrollfix>
48+
{% for nav_item in nav %}
49+
{% set path = "__nav_" ~ loop.index %}
50+
{{ item.render(nav_item, path, 1) }}
51+
{% endfor %}
52+
</ul>
53+
</nav>

‎docs/src/api/make_pages.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
import mkdocs_gen_files
77

8-
package = os.getenv("PACKAGE")
8+
package = os.getenv("PACKAGE", "datajoint")
99
nav = mkdocs_gen_files.Nav()
1010
for path in sorted(Path(package).glob("**/*.py")):
1111
with mkdocs_gen_files.open(f"api/{path.with_suffix('')}.md", "w") as f:

‎docs/src/citation.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,4 @@ If your work uses the DataJoint for Python, please cite the following manuscript
44

55
- Yatsenko D, Reimer J, Ecker AS, Walker EY, Sinz F, Berens P, Hoenselaar A, Cotton RJ, Siapas AS, Tolias AS. DataJoint: managing big scientific data using MATLAB or Python. bioRxiv. 2015 Jan 1:031658. doi: https://doi.org/10.1101/031658
66

7-
- DataJoint for Python - [RRID:SCR_014543](https://scicrunch.org/resolver/SCR_014543) - Version `Enter version here`
7+
- DataJoint for Python - [RRID:SCR_014543](https://scicrunch.org/resolver/SCR_014543) - Version `Enter datajoint-python version you are using here`

0 commit comments

Comments
 (0)
0