Elpy: wiki overlaps with documentation and README

[aspiers]

Hi there, it's a really nice problem to have too much documentation ;-) But I would like to suggest that the wiki documentation and much of the README.md should be merged into docs/, and then the wiki retired, because:

• Having more than one source means they will inevitably diverge and cause confusion. For newcomers (like me) don't know whether to follow https://github.com/jorgenschaefer/elpy/blob/master/README.rst or https://elpy.readthedocs.io/en/latest/introduction.html#installation or https://github.com/jorgenschaefer/elpy/wiki/Installation.
• When code changes impact the documentation, the docs can be updated in the same commit as the code, ensuring they stay in sync.
• The wiki is not subject to peer review, therefore harder to maintain quality.

Is this something which you could agree to in principle, even if you don't have time to do it? If so, I might be able to contribute a few PRs in this direction.

[aspiers]

Just noticed that the README also covers installation, so this is three different places to choose from. Updated the issue accordingly.

[gopar]

Hey,

Thanks for bringing this up :)

I see your point, and I agree. Personally, I would prefer that the README still have a quick "Get Started Guide" where it shows the bare minimum to get elpy running, and then link to the docs for everything else.

As for the wiki, I believe some stuff there is outdated, perhaps move some of the sections to the docs.

@galaunay Thoughts about moving mostly everything to https://elpy.readthedocs.io/?

I don't know anything about how https://elpy.readthedocs.io/ is updated, or if it can simply be updated by editings the rst files. :P

[galaunay]

@aspiers I do agree that the wiki should be removed (I just read through it quickly and there is a lof of obsolete information in there). I think the relevant information could be perfectly merged in the docs as you suggest.
I can find some time to work on that, but if you are willing to contribute, that would help a lot.

@gopar I find as well that the readme could be more appealing and reflect better what is Elpy. A quick start section would be a very good idea. I was also thinking about a having a short list of features (with links to the doc). Would it be only to show that Elpy can offer the same kind of features (sometimes more ?) than other IDEs.

I don't know anything about how https://elpy.readthedocs.io/ is updated, or if it can simply be updated by editings the rst files. :P

It will, as soon as I can get in touch with Jorgen and get access to Elpy's readthedocs account :).

[aspiers]

Awesome, thanks folks!

@galaunay commented on May 31, 2019 12:36 AM:

It will, as soon as I can get in touch with Jorgen and get access to Elpy's readthedocs account :).

It should be set up to automatically update whenever GitHub updates:

https://docs.readthedocs.io/en/stable/webhooks.html

but if not, it looks like it would be easy to set that up.

[galaunay]

Jorgen just replied to my mail this morning.
Apparently it was automatic but the hook broke (somehow...) 5 months ago.

I have control on readthedoc now, so I should be able to fix this.

[aspiers]

Fantastic!

[galaunay]

I started a PR to address what we discussed here (#1608).

So far I just reformatted the readme.

I also realised debugging was not documented, to I'll try to add that as well.

Any help or comment would be welcome :)

[azzamsa]

@galaunay many project now seems to use docs/ instead of wiki. Wiki is very easy to get out of sync.

[galaunay]

PR #1608 is almost finished for me, I just need to review it one last time for spelling mistakes and details.
I basically merged the wiki to the docs, tried to re-organise both the readme and the docs to a more sensible structure and add some missing doc sections.

If you have some time to go through the modifications, any feedback would be very helpful (especially if you don't like them). You can access the new readme here and the new docs there.

[aspiers]

Awesome, thanks a lot! I'll let you know if I spot any things which can be improved.

[galaunay]

Associated PR has now been merged.
I guess I can close this.