Convert the README from rst to md #1862
Conversation
for more information, see https://pre-commit.ci
webknjaz
added
docs
| @@ -0,0 +1,564 @@ | |||
| [](https://jazzband.co/) | |||
There was a problem hiding this comment.
Plz make all the link and image URLs detached so that it's easier to follow the syntax when these things are smashed together. Decoupling them also makes it possible to reuse some of the references and maintain them in a detached manner.
Note that the original document already follows this practice. The new one must keep it in place.
| Similar to `pip`, `pip-tools` must be installed in each of your project's | ||
| [virtual environments](https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments): | ||
|
|
||
| ``` |
There was a problem hiding this comment.
For code snippets with shell prompts and command output, always use the console highligher:
| ``` | |
| ```console |
| A set of command line tools to help you keep your `pip`-based packages fresh, | ||
| even when you've pinned them. You do pin them, right? (In building your Python application and its dependencies for production, you want to make sure that your builds are predictable and deterministic.) | ||
|
|
||
| [](https://github.com/jazzband/pip-tools/raw/main/img/pip-tools-overview.svg) |
| Suppose you have a 'foobar' Python application that is packaged using `Setuptools`, | ||
| and you want to pin it for production. You can declare the project metadata as: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Please, keep all the lexer specifications from the original document.
| ``` | |
| ```toml |
|
|
||
| Now, run `pip-compile requirements.in`: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Thank you for starting this off! Here's a few things that this PR needs to address before it's ready:
- make the external links detached from the places where they are used (I've noted a few places via inline comments but there's more)
- preserve the original code block lexers — it's important for syntax highlighting; there's a few inline notes but you need to inspect all of them
- fix the Sphinx inclusion; in the current state, it won't find the removed file @ https://github.com/jazzband/pip-tools/blob/main/docs/index.rst — you'll probably need to convert that document to MyST markdown too.
As one of the acceptance criteria, please make sure that the RTD build does not fail, then ensure that https://pip-tools--1862.org.readthedocs.build/en/1862/ renders the same as https://pip-tools.readthedocs.io/en/latest/.
@webknjaz This is a generic problem with RTD since urllib3 version 2 was released a few days ago. It should be fixed like in pypa/twine#991 |
No, the one I was referring to is caused by the PR. |
Do you mean the workflow "QA / build-docs" or "docs/readthedocs.org:pip-tools"? The |
I mean RTD. But the CI job would also fail. I haven't looked into the logs. This is solely based on the observation that |
|
@chrysle but please feel free to send a PR updating the RTD config. This is a welcome change, just not directly related to what's happening in this one. |
I've made one myself: #1864 |
This PR converts the documentation from README.rst to README.md
Related: #1856
Contributor checklist
Maintainer checklist
backwards incompatible,feature,enhancement,deprecation,bug,dependency,docsorskip-changelogas they determine changelog listing.