Proposal for cookiecutting sandboxed environments

[noelmcloughlin]

When using this tool in a sandboxed environment there are issues with poetry and mkdocs.

Problems.

1. Poetry: Our README states: In sandboxed environments (proxy or internal repositories), you must configure poetry source in ~/.config/pypoetry/pyproject.toml to allow software installation

2. Mkdocs: CDN is blocked so cannot retrieve mermaid.min.js

Potential solution

One solution updating cookiecutter.json to model a sandboxed user (default "no"):

• Poetry: We could manage poetry repository using cookiecutter rendering. However, poetry repository can also be supplied by environment variable instead.

• CDN: Cookiecutter seems only solution. The documentation suggests we could render correct mermaid source in mkdocs.yml by defaulting to standard CDN but allowing sandboxed user to say I need (a) different CDN/version OR (b) I need to use local src/docs/mermaid.min.js file.

I need to do some testing on both issues.

[dalito]

An alternative to modifying the project is to add a poetry config file for the system/user, see https://python-poetry.org/docs/configuration/

I do this plus use a global (company wide) pip.ini/pip.conf for pip, pipx etc. (unfortunately poetry does not respect the pip-config but requires its own). We use devpi as local pypi-replacement and another server for javascript-libs like mermaid.

[noelmcloughlin]

Agree - thanks for confirming so cookiecutter is not good solution for poetry nuances! I also noticed README has incorrect filename (should be ~/.config/pypoetry/config.toml not ~/.config/pypoetry/pyproject.toml). I'll raise fix PR.

The remaining issue is blocked CDN.

[noelmcloughlin]

The documentation describes three possible ways to load mermaid2:

1. You may specify a different version of the Mermaid library, like so:

   plugins:
   - search
   - mermaid2:
     version: 10.9.0

2. You may, however, specify your own version, using to the javascript parameter of Mermaid2 .. The files can be found on unpkg or jsdelivr.com.

   plugins:
   - search
   - mermaid2:
     javascript: https://unpkg.com/mermaid@10.9.0/dist/mermaid.esm.min.mjs 

3. In case you wish to use local version of the Mermaid.js library, you can do so.

   plugins:
   - search
   - mermaid2:
     javascript: js/mermaid.min.js  

   POSSIBLE SOLUTION

If we included a snapshot in src/docs/js/mermaid.min.js then cookiecutter offers solution to blocked CDN:

cookiecutter.json (allow some people to choose local library)

 ...
 `"mermaid_library_source": ["standard", "local"],`
 ...

mkdocs.yaml (version may not match local JS but this is nuance)

 plugins:
  - search
  - mermaid2:
       version: 10.9.0
 {%- if cookiecutter.mermaid_library_source == "local" -%}
     javascript: js/mermaid.min.js   # may be older version
 {%- endif %}

[dalito]

Ok. I had another look how I did it: I use a plugin poetry-plugin-pypi-mirror. Sorry, completely forgot about the plugin.

The config.toml is in C:\Users\<username>\AppData\Roaming\pypoetry (Windows).

[virtualenvs]
in-project = true

[plugins]
[plugins.pypi_mirror]
# https://jacobhenner.com/2022/11/pypi-mirror-support-in-poetry/
# Plugin must be installed with "poetry self add poetry-plugin-pypi-mirror"
# or "pipx inject poetry poetry-plugin-pypi-mirror"
url = "https://pypi-mirror.example.com/group/stable/+simple/"