Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/smarie/mkdocs-gallery
Same features as sphinx-gallery (https://sphinx-gallery.github.io/) but on mkdocs (https://www.mkdocs.org/) (no sphinx dependency !).
https://github.com/smarie/mkdocs-gallery
binder code example figure gallery generator jupyter latex mkdocs notebook page sphinx-gallery web
Last synced: 2 days ago
JSON representation
Same features as sphinx-gallery (https://sphinx-gallery.github.io/) but on mkdocs (https://www.mkdocs.org/) (no sphinx dependency !).
- Host: GitHub
- URL: https://github.com/smarie/mkdocs-gallery
- Owner: smarie
- License: bsd-3-clause
- Created: 2021-11-10T15:51:30.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-09-30T08:32:38.000Z (3 months ago)
- Last Synced: 2024-12-14T23:09:48.475Z (9 days ago)
- Topics: binder, code, example, figure, gallery, generator, jupyter, latex, mkdocs, notebook, page, sphinx-gallery, web
- Language: Python
- Homepage: https://smarie.github.io/mkdocs-gallery
- Size: 91.9 MB
- Stars: 40
- Watchers: 4
- Forks: 16
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mkdocs-gallery
*[Sphinx-Gallery](https://sphinx-gallery.github.io/) features for [mkdocs](https://www.mkdocs.org/) (no [Sphinx](sphinx-doc.org/) dependency !).*
[](https://pypi.python.org/pypi/mkdocs-gallery/) [](https://github.com/smarie/mkdocs-gallery/actions/workflows/base.yml) [](https://smarie.github.io/mkdocs-gallery/reports/junit/report.html) [](https://smarie.github.io/mkdocs-gallery/reports/coverage/index.html) [](https://codecov.io/gh/smarie/mkdocs-gallery) [](https://smarie.github.io/mkdocs-gallery/reports/flake8/index.html)
[](https://smarie.github.io/mkdocs-gallery/) [](https://pypi.python.org/pypi/mkdocs-gallery/) [](https://pepy.tech/project/mkdocs-gallery) [](https://pepy.tech/project/mkdocs-gallery) [](https://github.com/smarie/mkdocs-gallery/stargazers) [](https://doi.org/10.5281/zenodo.5786851)
Do you love [Sphinx-Gallery](https://sphinx-gallery.github.io/) but prefer [mkdocs](https://www.mkdocs.org/) over [Sphinx](sphinx-doc.org/) for your documentation ? `mkdocs-gallery` was written for you ;)
It relies on [mkdocs-material](https://squidfunk.github.io/mkdocs-material) to get the most of mkdocs, so that your galleries look nice!
**This is the readme for developers.** The documentation for users is available here: [https://smarie.github.io/mkdocs-gallery/](https://smarie.github.io/mkdocs-gallery/)
## Want to contribute ?
Contributions are welcome ! Simply fork this project on github, commit your contributions, and create pull requests.
Here is a non-exhaustive list of interesting open topics: [https://github.com/smarie/mkdocs-gallery/issues](https://github.com/smarie/mkdocs-gallery/issues)
## `nox` setup
This project uses `nox` to define all lifecycle tasks. In order to be able to run those tasks, you should create python 3.7 environment and install the requirements:
```bash
>>> conda create -n noxenv python="3.7"
>>> activate noxenv
(noxenv) >>> pip install -r noxfile-requirements.txt
```
You should then be able to list all available tasks using:
```
>>> nox --list
Sessions defined in \noxfile.py:
* tests-2.7 -> Run the test suite, including test reports generation and coverage reports.
* tests-3.5 -> Run the test suite, including test reports generation and coverage reports.
* tests-3.6 -> Run the test suite, including test reports generation and coverage reports.
* tests-3.8 -> Run the test suite, including test reports generation and coverage reports.
* tests-3.7 -> Run the test suite, including test reports generation and coverage reports.
- docs-3.7 -> Generates the doc and serves it on a local http server. Pass '-- build' to build statically instead.
- publish-3.7 -> Deploy the docs+reports on github pages. Note: this rebuilds the docs
- release-3.7 -> Create a release on github corresponding to the latest tag
```
## Running the tests and generating the reports
This project uses `pytest` so running `pytest` at the root folder will execute all tests on current environment. However it is a bit cumbersome to manage all requirements by hand ; it is easier to use `nox` to run `pytest` on all supported python environments with the correct package requirements:
```bash
nox
```
Tests and coverage reports are automatically generated under `https://smarie.github.io/mkdocs-gallery/docs/reports` for one of the sessions (`tests-3.7`).
If you wish to execute tests on a specific environment, use explicit session names, e.g. `nox -s tests-3.6`.
## Editing the documentation
This project uses `mkdocs` to generate its documentation page. Therefore building a local copy of the doc page may be done using `mkdocs build -f mkdocs.yml`. However once again things are easier with `nox`. You can easily build and serve locally a version of the documentation site using:
```bash
>>> nox -s docs
nox > Running session docs-3.7
nox > Creating conda env in .nox\docs-3-7 with python=3.7
nox > [docs] Installing requirements with pip: ['mkdocs-material', 'mkdocs', 'pymdown-extensions', 'pygments']
nox > python -m pip install mkdocs-material mkdocs pymdown-extensions pygments
nox > mkdocs serve -f https://smarie.github.io/mkdocs-gallery/docs/mkdocs.yml
INFO - Building documentation...
INFO - Cleaning site directory
INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration:
- long_description.md
INFO - Documentation built in 1.07 seconds
INFO - Serving on http://127.0.0.1:8000
INFO - Start watching changes
...
```
While this is running, you can edit the files under `https://smarie.github.io/mkdocs-gallery/docs/` and browse the automatically refreshed documentation at the local [http://127.0.0.1:8000](http://127.0.0.1:8000) page.
Once you are done, simply hit `` to stop the session.
Publishing the documentation (including tests and coverage reports) is done automatically by [the continuous integration engine](https://github.com/smarie/mkdocs-gallery/actions), using the `nox -s publish` session, this is not needed for local development.
## Packaging
This project uses `setuptools_scm` to synchronise the version number. Therefore the following command should be used for development snapshots as well as official releases: `python setup.py sdist bdist_wheel`. However this is not generally needed since [the continuous integration engine](https://github.com/smarie/mkdocs-gallery/actions) does it automatically for us on git tags. For reference, this is done in the `nox -s release` session.
### Merging pull requests with edits - memo
As explained in github ('get commandline instructions'):
```bash
git checkout -b - main
git pull https://github.com//mkdocs-gallery.git --no-commit --ff-only
```
if the second step does not work, do a normal auto-merge (do not use **rebase**!):
```bash
git pull https://github.com//mkdocs-gallery.git --no-commit
```
Finally review the changes, possibly perform some modifications, and commit.