Move docs to main repo?


(Jakob Borg) #21

True. I’ve been unable to find something like an online wysiwyg editor that would assist in creating a PR. As far as I can tell it doesn’t exist, so the workflow would be the usual edit-on-github link or an actual source checkout.

Sticking to that, the only difference from the current setup would be the backend text format and rendering.

I’m still wondering whether a move to markdown and a standard static site generator (jekyll, hugo, …) wouldn’t be an improvement on the current sphinx setup. Both in ease of editing and in maintenance.


(Audrius Butkevicius) #22

What’s the actual problem we are trying to solve here. Who was complaining that there isn’t a wysiwyg editor?


(Jakob Borg) #23

There’re two entirely different problems I want to solve.

The first is that I want to integrate the docs with the code more. As is, there is no good way to tie docs to a given release version and no good way to make code + docs changes (so we forget the latter). This is all for me. If I could expect API changes to also change the relevant docs in the same PR, and then later do a git diff v1.0.0..v1.5.0 -- docs/rest/ that would be hugely helpful to me.

The second is that we don’t get a lot of “external” contributions, in my opinion. There are probably lots of reasons for this and I can’t know them all, but the docs being tricky to get your head around as a newbie can’t help the situation. Currently the README talks about a weird compilation process and tools and the docs are in an odd format (that I’ve personally grown to dislike, too). I suspect a more Wiki-like approach here would help. A WYSIWYG editor probably wouldn’t hurt but I don’t think it’s essential either.

I was thinking GitBook might solve both these things in one change. I’m not necessarily convinced that’s the case any more, but those are the problem statements.


(xor-gate) #24

For the closed-source cloud part:

  • RST is more feature-full then all those markdown “standards”
  • Pandoc is your friend when the GitBook service goes offline or want to render e.g epub/html offline.
  • Not sure if Hugo static site generator is able to render something usefull from the GitBook markdown format (for offline use)

Just my ideas.