Resolves #2058: Improve developer installation, remove pip_install_strictdoc_deps.py

[nogjam]

pip_install_strictdoc_deps.py requires a manual pip install of the toml module before it works with a fresh virtual environment. We can achieve a working installation much easier with a virtual environment (which is better practice anyway) and pip. This begs the question of whether this script is needed at all. Delete it, and make the corresponding updates to the Dev Guide and tox.ini.

[nogjam]

I am aware that I have broken invoke server (at least) by deleting pip_install_strictdoc_deps.py. Re-evaluating, learning about the invoke check task...

[nogjam]

invoke check before changes:

********************
UNSUPPORTED: StrictDoc HTML2PDF integration tests :: features/html2pdf/06_system_chromedriver/test.itest (6 of 6)
********************
Failed Tests (5):
  StrictDoc HTML2PDF integration tests :: features/html2pdf/01_empty_document/test.itest
  StrictDoc HTML2PDF integration tests :: features/html2pdf/02_three_top_level_requirements/test.itest
  StrictDoc HTML2PDF integration tests :: features/html2pdf/03_three_documents_with_assets/test.itest
  StrictDoc HTML2PDF integration tests :: features/html2pdf/04_composable_document_with_assets/test.itest
  StrictDoc HTML2PDF integration tests :: features/html2pdf/05_generate_bundle_document/test.itest

invoke check after changes (no difference):

********************
UNSUPPORTED: StrictDoc HTML2PDF integration tests :: features/html2pdf/06_system_chromedriver/test.itest (6 of 6)
********************
Failed Tests (5):
  StrictDoc HTML2PDF integration tests :: features/html2pdf/01_empty_document/test.itest
  StrictDoc HTML2PDF integration tests :: features/html2pdf/02_three_top_level_requirements/test.itest
  StrictDoc HTML2PDF integration tests :: features/html2pdf/03_three_documents_with_assets/test.itest
  StrictDoc HTML2PDF integration tests :: features/html2pdf/04_composable_document_with_assets/test.itest
  StrictDoc HTML2PDF integration tests :: features/html2pdf/05_generate_bundle_document/test.itest

[nogjam]

I am aware that I have broken invoke server (at least) by deleting pip_install_strictdoc_deps.py. Re-evaluating, learning about the invoke check task...

I have re-evaluated this and learned more about using invoke check. This should be ready for review.

[nogjam]

Hmm, I am noticing one more thing: I mistakenly forgot to update the .rst docs in addition to the .sdoc docs. Is this solvable with an invoke docs?

EDIT: Just tried it. Although it does indeed update the .rst docs, this invocation also seems to generate a larger diff than I was expecting:

➜ git diff --stat
 docs/sphinx/source/_assets/StrictDoc_Workspace-Roadmap.drawio.png | Bin 845541 -> 859334 bytes
 docs/sphinx/source/strictdoc_01_user_guide.rst                    |  16 +++++++++++++---
 docs/sphinx/source/strictdoc_03_faq.rst                           |  34 ++++++++++++++++++++++++++++------
 docs/sphinx/source/strictdoc_04_release_notes.rst                 |  30 +++++++++++++++++++++++++++---
 docs/sphinx/source/strictdoc_11_developer_guide.rst               |  25 +++++++++++++++++--------
 5 files changed, 85 insertions(+), 20 deletions(-)

Is this desirable?

[stanislaw]

Hey @nogjam , thanks for reviewing this setup step and contributing a possible improvement.

Before implementing the current solution, I had definitely tried doing the setup your way, but I encountered a limitation of pip install ., and that is that it installs both the dependencies AND the project itself. This means that you end up having a sort of undefined behavior because from then on, imports from any Python file will likely work against the installed package, not against the source files of StrictDoc. I double-checked if there was an option for pip install to avoid that kind of behavior and couldn't find it at the time.

Could you confirm that this problem indeed exists and suggest a possible workaround?

Thanks for looking into this. I am all in for simpler solutions.

[nogjam]

Hmm, I thought only pip install --editable . installed the current project, not pip install . . I'll look into this.

This means that you end up having a sort of undefined behavior because from then on, imports from any Python file will likely work against the installed package, not against the source files of StrictDoc.

Could you please clarify and/or provide an example of this undesirable behavior?

[nogjam]

Here's some more information from https://setuptools.pypa.io/en/latest/userguide/development_mode.html:

An “editable installation” works very similarly to a regular install with pip install ., except that it only installs your package dependencies, metadata and wrappers for console and GUI scripts.

Please note that, by default an editable install will expose at least all the files that would be available in a regular installation. However, depending on the file and directory organization in your project, it might also expose as a side effect files that would not be normally available.

Is the kind of problem you're thinking of something that invoke check would find? I can confirm that running it both with and without the "strictdoc" package installed produces the same results: 5 failed tests, as shown above. I'm using Python 3.12.3, FWIW.