adding documentation

[choldgraf]

This PR adds a basic Sphinx site using the default Sphinx ReadTheDocs theme.

It takes the current README and splits it up into a few separate pages that can be navigated with a TOC to the left. I didn't really change any of the content of the documentation.

You can preview what this looks like here:

http://predictablynoisy.com/jupytext/

What do you think @mwouts ? I think if you like the approach in general, there are a couple things that could be improved:

• Make sure all the links work (e.g. there were some internal links that might be broken since things are on a different page)
• Set up a readthedocs site to host this documentation

Let me know if / how you'd like to proceed!

[codecov]

Codecov Report

Merging #237 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #237   +/-   ##
=======================================
  Coverage   99.23%   99.23%           
=======================================
  Files          65       65           
  Lines        6176     6176           
=======================================
  Hits         6129     6129           
  Misses         47       47

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update fd6569d...cfb5975. Read the comment docs.

[mwouts]

Thank you so much @choldgraf! That will make it much easier to circulate into the documentation. I will integrate this soon.

[mwouts]

@choldgraf , this works well, thanks!

I have been able to compile the documentation to html locally, and to adjust a few things (the table of contents in particular).

Now I think I will make the README shorter, and setup RTD, with a yaml file if I can. This will probably take me a few more days... Also seeing the structure of the documentation is interesting - maybe I will also make a few more adjustments there as well!

[choldgraf]

@mwouts if you'd like, I am happy to help set up a readthedocs page (I believe you'd need to give me access to the page on readthedocs). I'd also be happy to make the README shorter (I usually just keep it to short explanation, installation, basic usage, and a link to docs) but I didn't wanna clutter up this PR if that'd get more complicated. How would you like me to proceed? :-)

[mwouts]

Hello @choldgraf , I have added choldgraf as a maintainer at https://readthedocs.org/projects/jupytext/. Regarding the README, well maybe I let this file to you, and I focus on the structure of the docs themselves? Is that convenient for you?

[choldgraf]

hey @mwouts - I just pushed a few commits that

1. Streamlined the README and linked out more to the documentation, so it's a bit shorter now
2. Made some small changes in the documentation for readability/structure.

I see that readthedocs is now building the documentation! I think once this PR is merged, we can see whether it propagates to the page (it should, unless there is a build error somewhere)

I'm happy to give this one a merge and then spot-check other bugs and minor improvements in the documentation, if you'd like.

[mwouts]

Chris, I have been able to udpate the links, and merged this PR. The doc works locally with make html. However I see that readthedocs complains about a content.rst file that is not there:

Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/jupytext/checkouts/latest/docs/contents.rst not found

Do you see how we could fix that? Thanks!

[choldgraf]

@mwouts lemme take a look!

[mwouts]

The issue has been fixed with #242 - thanks again Chris for your contribution! That's a very nice step forward!