Rename src directory to techdocs_core #223
Conversation
Rename the src directory so it install into something sensible in python site-packages.
We're missing the latest stable release and 3.7 is no longer supported.
techdocs_core/__init__.py
Outdated
There was a problem hiding this comment.
Can you expand on why this change is needed? It's been like this, as far as I can tell, for the life of the plugin so would like to know why it needs to be changed. 👍
There was a problem hiding this comment.
Note: not against this change per say but need more information to feel comfortable with it.
There was a problem hiding this comment.
Quick experiment is best:
pip install .
...lots of stuff...
Successfully installed mkdocs-techdocs-core-1.4.2
(mkdocs-techdocs-core) ➜ mkdocs-techdocs-core git:(main) ✗ ls -lh ~/PRACA/venvs/mkdocs-techdocs-core/lib/python3.12/site-packages/src
total 32
-rw-r--r--@ 1 lukasz.jernas staff 0B 22 paź 19:18 __init__.py
drwxr-xr-x@ 5 lukasz.jernas staff 160B 22 paź 19:18 __pycache__
-rw-r--r--@ 1 lukasz.jernas staff 6,3K 22 paź 19:18 core.py
-rw-r--r--@ 1 lukasz.jernas staff 5,8K 22 paź 19:18 test_core.pyNow lets get a new package
(mkdocs-techdocs-core) ➜ nottechdocs ls -lR
total 8
-rw-r--r-- 1 lukasz.jernas wheel 0 22 paź 19:33 README.md
-rw-r--r-- 1 lukasz.jernas wheel 0 22 paź 19:33 requirements.txt
-rw-r--r-- 1 lukasz.jernas wheel 1431 22 paź 19:33 setup.py
drwxr-xr-x 4 lukasz.jernas wheel 128 22 paź 19:32 src
./src:
total 8
-rw-r--r-- 1 lukasz.jernas wheel 0 22 paź 19:28 __init__.py
-rw-r--r-- 1 lukasz.jernas wheel 98 22 paź 19:32 nottechdocs.py
(mkdocs-techdocs-core) ➜ nottechdocs pip install .
Processing /private/tmp/nottechdocs
Installing build dependencies ... done
Getting requirements to build wheel ... done
Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: not_techdocs
Building wheel for not_techdocs (pyproject.toml) ... done
Created wheel for not_techdocs: filename=not_techdocs-1.4.2-py3-none-any.whl size=1988 sha256=fbd855c3c12b95b25c483b2c081c5f5e449169a24bedb07cc2053ba50b608f5f
Stored in directory: /private/var/folders/rf/nnmkkn0s6gb_k9195jqzhhwm0000gp/T/pip-ephem-wheel-cache-m_54du9w/wheels/17/e4/9b/1c1701897e538679d5e61f08276a22c87848f54af6dfd33c99
Successfully built not_techdocs
Installing collected packages: not_techdocs
Successfully installed not_techdocs-1.4.2
(mkdocs-techdocs-core) ➜ mkdocs-techdocs-core git:(main) ✗ ls -lh ~/PRACA/venvs/mkdocs-techdocs-core/lib/python3.12/site-packages/src
total 40
-rw-r--r--@ 1 lukasz.jernas staff 0B 22 paź 19:33 __init__.py
drwxr-xr-x@ 5 lukasz.jernas staff 160B 22 paź 19:33 __pycache__
-rw-r--r--@ 1 lukasz.jernas staff 6,3K 22 paź 19:18 core.py
-rw-r--r--@ 1 lukasz.jernas staff 98B 22 paź 19:33 nottechdocs.py
-rw-r--r--@ 1 lukasz.jernas staff 5,8K 22 paź 19:18 test_core.pyOoops, now the new package pollutes the old one and we get all sorts of weird issues.
This works as long as it's the only python packages with a top-level src directory, otherwise we have a problem
There was a problem hiding this comment.
Great, this helps. I understand the technical aspect now. Could you share a real example now of what you are doing that causes this? If I understand it correctly you have other python packages you are using in you Backstage deployment leading to this. Are these custom things unrelated to TechDocs or are these other MkDocs plugins (custom or open source)?
There was a problem hiding this comment.
I don't have an example at hand, but I did hit the issue with other packages in my life and it seems to be the de-facto standard, as it adheres to PEP-423 giving more meaningful names to modules.
There was a problem hiding this comment.
Also if someone would like to package it for a distribution, then they might hit that issue more easily given a lot of packages.
There was a problem hiding this comment.
Sorry for the delay, thanks for sharing that PEP, that helped a lot as well. 👍
.github/workflows/pypi-publish.yml
Outdated
| steps: | ||
| # Publish mkdocs-techdocs-core to PyPI | ||
| - uses: actions/checkout@v4 | ||
| - name: Set up Python ${{ matrix.python-version }} | ||
| uses: actions/setup-python@master | ||
| - name: Set up Python 3.8 |
There was a problem hiding this comment.
Would it make sense to go all the way to 3.13 for this? I can't tell what pypa/gh-action-pypi-publish supports at quick glance though.
There was a problem hiding this comment.
Alright, I'm good with these changes. But, sorry, I think we should update the PR title and description as there's more to this PR now - renovate and lint updates, various action updates, etc. That way we can link to this PR when we do the release and update the Changelog.
|
@awanlin maybe I should split this PR into parts? one with the directory change and the rest with the updates? |
Rename the src directory so it install into something sensible in python site-packages.
Add Python 3.12 to test harness and set publish job to 3.8
We're missing the latest stable release and 3.7 is no longer supported.