README: Add formatting and amend doc build instructions

[erlend-aasland]

Additionally:

• add formatting to Git branch names
• add formatting to Python module names
• consistently recommend 'python3 -m pip' iso. 'pip'
• consistently use 'python3' iso. 'python' for command line examples
• spell out Python version support

[erlend-aasland]

BTW; CI runs should be disabled for PRs like this.

[acolomb]

What's wrong with using pip as a command?

Sorry, I have next to no experience with configuring GitHub actions. How would we exclude CI runs for certain changes? Is it worthwhile investigating that?

[christiansandberg]

I don't think python3 even works on Windows.

[erlend-aasland]

André:

What's wrong with using pip as a command?

IIRC, because it's easy to end up using the "wrong" pip. Explicitly executing pip as a module using your preferred python3 command, ensures you're installing packages for the correct Python installation.

See also the pip docs: https://pip.pypa.io/en/stable/user_guide/

Christian:

I don't think python3 even works on Windows.

I don't use Windows, but yes, I believe you'll have to use py -m pip. IIRC, there are some differences depending on which shell you use (PowerShell vs. CMD.EXE vs. Git Bash, etc.), though.

André:

Sorry, I have next to no experience with configuring GitHub actions. How would we exclude CI runs for certain changes? Is it worthwhile investigating that?

I also realised there is no docs build CI. I'll create an issue with some suggested CI improvements.

---

Thanks both of you for reviewing.

[sveinse]

What's wrong with using pip as a command?

On windows, running pip runs pip.exe. Any operations that involves update of pip itself will fail, as Windows unfortunately blocks the executable pip.exe. So it is common practice to run python -m pip (if venv) or py -m pip (if global) for that reason.

I don't think python3 even works on Windows.

python3 is a non-Windows thing, and py.exe has been established as the go-to for Windows. However, all (three?) targets have python as executable when using a virtual environment ¹. I find that as good middle ground for writing documentation.

Footnotes

1. <python rant> For some unfathomable reason, all OS except Windows use bin/ as the executable directory in virtual environments, while Windows use Scripts\. Its an irritating obstacle for making OS-independent interactions and scripts against virtual environments and extremely annoying. </python rant> ↩

[acolomb]

Well the Windows problem of pip install -U pip isn't relevant here, as that's not what the listed command is doing.

Please go back to pip and python as the most basic commands that illustrate what needs to be done. Different environments may need adjustments, but there's no copy-paste-ability guarantee anywhere in the document. :-)

If the pip maintainers think it's too dangerous to use the installed pip[.exe] binary, then they should remove it. People can always just do alias pip="python -m pip" if they frequently need it. But the intention here is to show what needs to be installed, not to introduce correct pip command line usage.

[sveinse]

If the pip maintainers think it's too dangerous to use the installed pip[.exe] binary, then they should remove it. People can always just do alias pip="python -m pip" if they frequently need it. But the intention here is to show what needs to be installed, not to introduce correct pip command line usage.

FYI: Setuptools docs and pip docs consequently use -m pip in their documentation. I don't know why thou.

[erlend-aasland]

But the intention here is to show what needs to be installed, not to introduce correct pip command line usage.

Sure, but IMO those are not conflicting goals. Well, I updated the PR according to your remarks. PTAL.

[acolomb]

@erlend-aasland Hm... Unfortunately this broke our PyPI uploads, as the Sphinx roles in README.rst are not acceptable for the parsing on PyPI. Will have to revert some of the formatting and try again with a v2.4.1 release.

See https://github.com/canopen-python/canopen/actions/runs/16746953346/job/47407670531