docs: update install doc #1426
docs: update install doc #1426
Conversation
2bndy5
force-pushed
the
update-install-doc
branch
from
a046e58 to
b7f1e1f
Compare
| +-------------+----------------+------------+ | ||
| | pygit2 | Python | libgit2 | | ||
| +-------------+----------------+------------+ | ||
| | 1.19 | 3.10 - 3.14(t) | 1.9 | |
There was a problem hiding this comment.
This should only get merged once the next release is deployed. @jdavid Please let me know if the next release will not be tagged as v1.19.0
2bndy5
force-pushed
the
update-install-doc
branch
from
b7f1e1f to
92b9974
Compare
| .. code-block:: text | ||
| $ python -c 'import pygit2' | ||
| python -c 'import pygit2' |
There was a problem hiding this comment.
This is a text block showing a shell session, so maybe keep the shell prompt?
There was a problem hiding this comment.
Technically, text is used here to intentionally disable syntax highlighting.
I specifically chose text instead of shell because the pygments' syntax highlighting (employed by sphinx) produces odd coloring for error messages (especially for gcc errors/warnings). And the main purpose of this snippet is to show an error message.
Without any special config, sphinx allows docutils to automatically use pygments' python lexer to highlight literal-block nodes (docutils API term for ::\n\n code block here).
Observe this snippet on master branch rendered as Python code (with syntax highlighting):
There was a problem hiding this comment.
Ah, I meant keeping the $, while also keeping the text part unchanged. I also agree that text looks better than shell or python, if shell-session is not available.
I just checked Pygments source and it seems console and shell-session are provided specifically for highlighting shell sessions like this, but I don't know if the Sphinx version for pygit2 has this support. If it's supported maybe we can have a try...
There was a problem hiding this comment.
$ is specific to bash. And while, this is a shell session, it is mostly agnostic of the actual shell being used (zsh, bash, nushell, etc). Admittedly, the .so part does hint at a Unix shell.
Also, (copied from OP):
- remove
$from code snippets for better (platform-agnostic) copy-n-paste. I replaced this with a caption if any code snippets implicitly rely on bash.
However, I did not add sphinx-copybutton extension to docs/conf.py (and the new docs/requirements.txt).
There was a problem hiding this comment.
I agree with you. I'm originally suggesting this because it's kinda "unnatural" for me to see a shell session without $PS1; I know many people or non-bash shells don't use $ but it's probably a convention that many people agree on. This is minor though, and I'm fine with either. Thank you for explaining!
There was a problem hiding this comment.
it's probably a convention that many people agree on
Assumptions are why I can't have nice things. They almost always get me in trouble.
I also have a habit of overthinking things. 😜
* resolves libgit2#1308 * resolves libgit2#1383 ### Changes * added docs/requirements.txt, so contributors can check changes locally before committing. * remove `$` from code snippets for better (platform-agnostic) copy-n-paste. I replaced this with a caption if any code snippets implicitly rely on bash. * update the version of libgit2 used * update table of version compatibility (assumes the next version is v1.19) * added implied requirements about building from source * cross linked "build from source" section for better doc navigation * fix link to libgit2 docs about building/installing * converted code snippet about building libgit2 on Windows to powershell syntax. I also added a caption to explain minimum CMake version used.
2bndy5
force-pushed
the
update-install-doc
branch
from
3288e9a to
acf5149
Compare
2 participants
Changes
$from code snippets for better (platform-agnostic) copy-n-paste. I replaced this with a caption if any code snippets implicitly rely on bash.