Refactor README

[atugushev]

What's the problem this feature will solve?

Since the README file has become quite large, perhaps it's time we consider refactoring it.

Describe the solution you'd like

• Make README small and concise focusing on important things
• Keep on README description, svg image, installation and basic usage of the pip-tools
• Move the other sections to https://pip-tools.rtfd.io/

References:

• https://github.com/pypa/pip
• https://github.com/pypa/build
• https://github.com/pypa/virtualenv
• https://github.com/pallets/click
• https://github.com/pytest-dev/pytest
• https://github.com/pytest-dev/pytest-asyncio

Alternative Solutions

N/A

Additional context

• https://fosstodon.org/@jamescooke/109954634904286238
• https://hachyderm.io/@jamescooke@fosstodon.org/110125938514902869

/cc @jamescooke

[chrysle]

* Keep on README description, svg image, installation and basic usage of the pip-tools
* Move the other sections to https://pip-tools.rtfd.io/

I'm +1 on this! I'd suggest a style like in the python packaging guide, with different Markdown files for the sections.

I also think intersphinx mapping should be configured for the many project references in the docs.

There is already an attempt to convert the README to Markdown (#1862), I would wait until this is finished. I'd refactor the index.rst file and convert it to Markdown then.

I would like to help with that, should I work on a PR?

[webknjaz]

I would like to help with that, should I work on a PR?

You could try picking up #1862 as it's not clear if @shatakshiiii wants to iterate on it anytime soon. Though, if you want to push commits into their branch, make sure to clearly communicate your intent in that PR comments and only add new commits on top without force-pushing the branch (unless they consent). Alternatively, you could try starting off of their branch (to get it, add their remote via git remote add shatakshiiii git@github.com:shatakshiiii/pip-tools.git to your local repo and you'll be able to fetch it (though using git fetch git@github.com:shatakshiiii/pip-tools.git would probably work too) — then, you'd push your own branch to your fork and make a separate PR.

I would wait until this is finished. I'd refactor the index.rst file and convert it to Markdown then.

Git is distributed in nature. So there's no technical blocker for doing this. If you want to separate out some content, you could add a new docs page without deleting it from the README and do the deletion later on. Although, there's already conflicts with #1862 so they'll need to be solved regardless. Since that PR is now marked as draft, maybe it's not worth paying much attention to it. We don't know when or if it'll be resurrected.

[chrysle]

Alternatively, you could try starting off of their branch (to get it, add their remote via git remote add shatakshiiii git@github.com:shatakshiiii/pip-tools.git to your local repo and you'll be able to fetch it (though using git fetch git@github.com:shatakshiiii/pip-tools.git would probably work too) — then, you'd push your own branch to your fork and make a separate PR.

Thanks! I'll do that.

Git is distributed in nature. So there's no technical blocker for doing this. If you want to separate out some content, you could add a new docs page without deleting it from the README and do the deletion later on.

Wouldn't that be confusing to the end reader? I guess with later on you mean in separate PRs. I'd rather do everything at once to reduce doubling content.

[webknjaz]

I guess with later on you mean in separate PRs. I'd rather do everything at once to reduce doubling content.

Sure, that'll do. I thought you were concerned about causing conflicts in Git so I suggested standalone PRs. But yes, I agree that it's nicer to have commits that move things rather than keeping the duplicates. Still, moving multiple sections out of README might be nice to have in separate PRs since small changes are easier/faster to merge and unrelated feedback portions don't have to block entire PRs and would be scoped to small patches.

[chrysle]

Could the feature request in #1633 be integrated using the sphinx extension sphinxcontrib-programoutput?

I'd tend to provide the following pages in the docs:

• pip-compile
• pip-sync
• installation ?
• FAQ

[webknjaz]

Maybe. There's a number of different extensions doing similar things...