Poetry: README.md is out of sync with docs/

[germn]

• [x] I have searched the issues of this repo and believe that this is not a duplicate.

Issue

Subj. It especially easy to see comparing README.md and docs/docs/cli.md "Commands" sections. For example in Readme.md:

• Whole introduction and section Global options is missing
• --src option is missing for new command
• --git, --path, --extras are missing for add command
  etc.

It's confusing and hard to maintain. Solution I see is to just leave minimal text and link to full documentation at poetry.eustace.io in Readme.md. Many projects acts this way, for example: django, flask, aiohttp.

What do you think about it?

[thernstig]

Glad you posted this, I've experienced the same thing. I only read the README.md to start with and there are many commands not included that can be found in https://poetry.eustace.io/docs/cli/. For example shell, run. There is also no mention in README.md how virtual environments are created.

So I agree with your conclusion & solution.

[darcydev]

I have made a PR that acts as an interim solution (until a link is provided to the full documentation at poetry.eustace.io in Readme.md).

The PR brings README.md inline with docs/docs/cli.md "Commands" sections

It's my first contribution, thank you! 😃

[thernstig]

@darcyprice Nice PR! I want to note that multiple parts are still missing, The cli.md describes many commands, such as shell and check that are not part of README.md. There are most likely much more missing, but I did not go through it all.

Maybe it would be better to re-write the README.md instead to point to the real documentation that is maintained, i.e. cli.md?

[darcydev]

@thernstig Thanks for the feedback.

I agree, that it's better to re-write README.md to point to the documentation, as README.md is currently lenghty, confusing and, as stated by @germn, difficult to maintain.

The exception is the 'Introduction' which outlines Poetry and details its advantages over Pipenv. I have retained that section, although adjusted the headings slightly, subject to your feedback.

I will make the PR shortly :)

[darcydev]

I've made a couple of formatting changes (in relation to heading names and heading-order) that I believe improves the readability now that README.md points to the full docs. Although, subject to your feedback of course :)

[thernstig]

@darcyprice Nice! I think it could require some work to refine, but it is a great start. I think the actual review is better left to a maintainer.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[thernstig]

Unstale

[finswimmer]

In the meantime the README.md contains only a short introduction to poetry. The complete documentation is in docs.