search

danielfrg / mkdocs-jupyter

Use Jupyter Notebook in mkdocs
https://mkdocs-jupyter.danielfrg.com
Apache License 2.0
367 stars 45 forks source link

docs: refresh CONTRIBUTING.md #125

Closed josephmcasey closed 1 year ago

josephmcasey commented 1 year ago

What are the steps to reproduce this issue?

  1. Go to https://github.com/danielfrg/mkdocs-jupyter/blob/main/CONTRIBUTING.md
  2. Follow documentation to best of ability

What happens?

Antique References

The following requires poetry 1.2.0a2 or newer and these poetry config.toml settings:

This references an old pre-release version of poetry, I was able to get this working with the latest version, so it could help to update this documentation to reflect experience with 1.4.0?

Missing Makefile

## Tests
make test
### Check linting and format
make check
make fmt

make: *** No rule to make target `test'. Stop.

The makefile was removed between https://github.com/danielfrg/mkdocs-jupyter/compare/0.20.1...0.21.0 by the changeset introduced via https://github.com/danielfrg/mkdocs-jupyter/pull/79/files . Perhaps here we could add a link to https://taskfile.dev/ and make recommendations such as task test-all, task fmt, and task check?

Opinionated or Simple Setup

I roughly had to discover or know to run the following commands from a mostly clean OSX environment:

poetry lock --no-update
conda create -n mkdocs_jupyter_py39 python=3.9 --yes
conda activate mkdocs_jupyter_py39
poetry install --all-extras
brew install n
n 16
brew install go-task
task check
task fmt
task test-all

It would be great to either let this OSS project rely on an always live containerized development environment like the ones offered for free by https://www.gitpod.io/ or have an express and explicit set installation instructions with assumptions on the contributors' development environment.

Opinionated Approach on Dependencies

I ran into the following bit rot issues, and I thought it might be useful for the maintainer to express a general recommendation on how contributors should resolve dependency issues. I have my own personal thoughts on how you might want me to do it based on your other PRs, but I thought it might help to express your preferred approach plainly.

➜ poetry install --all-extras
Installing dependencies from lock file
Warning: poetry.lock is not consistent with pyproject.toml. You may be getting improper dependencies. Run `poetry lock [--no-update]` to fix it.
➜ poetry lock --no-update   
Resolving dependencies... (0.1s)Invalid requirement (importlib-metadata (>='4.4') ; python_version < "3.10") found in markdown-3.3.5 dependencies, skipping
Resolving dependencies... (0.3s)Invalid requirement (tinycss2 (>=1.1.0<1.2) ; extra == 'css') found in bleach-5.0.0 dependencies, skipping
Resolving dependencies... (0.6s)
Warning: The locked version 3.3.5 for markdown is a yanked version. Reason for being yanked: Invalid dependency specified. Fixed in 3.3.6.

Recommending Visual Checks

I noticed that when starting my contribution that the images included in your README.md which illustrate the value of the library are not linked in the contribution document. After having wouldbe changeset authors setup the node and mkdocs process, it might be helpful to have a link to http://127.0.0.1:8000/demo/#plots

What versions of software are you using?

Operating System macOS: 13.2.1

Toolchain Version Python 3.9.16 Conda 23.1.0 NodeJS v16.19.1 Task 3.21.0

Library Version commit 4eec2264929c0729a6774dcf27f147c8cdb4bf23

danielfrg commented 1 year ago

Fixed on https://github.com/danielfrg/mkdocs-jupyter/pull/130