Documentation/site changes

[Diogo Baeder]

Hi guys,

Lately we've been having some issues with the way we manage our documentation - namely managing code pieces -. I also noticed that, despite how beautiful our website is (I really like it, its colors and features are awesome), it has some embedded problems:

__________________________
Diogo Baeder
http://diogobaeder.com.br

[Diogo Baeder]

Sorry, I hit the "send" button by accident...

Well, going on:

__________________________
Diogo Baeder
http://diogobaeder.com.br

[Diogo Baeder]

(sorry, hit the damn button AGAIN! Hey, Gmail, it shouldn't be THAT easy to send a message here! :-P )

The problems with the current website are:

• We're less visible to search engines (mainly Google) because of the current URL structuring (we don't have pages, but anchors instead, to delimit sections)
• It's harder to find certain specific pieces of information - for example, an API method -
• It's harder to share information with other people, as they will have to scroll the section you sent them until they find the piece of information they need

So, with some pain in my chest, I'd like to propose we migrate our current website to a website generated by Sphinx (http://sphinx-doc.org/), and hosted at Read the Docs (https://readthedocs.org/). We don't have to stick to the default theme, as there are some really nice Sphinx themes out there, and this would give us a group of features that I believe would help developers to use provy.

The only bad thing, besides loosing the neat context menu and the layout, which I really like, is that we would also have to migrate our docstrings to the format required by Sphinx. But I'm willing to put some big effort myself to do this, if you agree.

What do you say?

[rcmachado]

Hi Diogo,

Agreed! If you need some help, please open a branch and tell us :)

To be honest, I really hate the context menu on right click. It's intrusive and don't replace , IMHO, a real menu on a website.

Maybe, in future, we can create a sphinx theme more like the current website and use it on readthedocs.org (I really don't know if we can do that)?

Cheers,

Rodrigo Machado

[Fernando]

Totally agreed. I like a lot the sphinx based docs.

--
http://about.me/fernandogrd

[Bernardo Heynemann]

Go for it. ;)

Bernardo Heynemann
Developer @ globo.com

[Diogo Baeder]

Awesome, thanks for the feedback, guys! :-)

Cheers!

__________________________
Diogo Baeder
http://diogobaeder.com.br

[Diogo Baeder]

Thanks, Rodrigo, that would help a lot! If we have a consensus of doing it, I'll let you know, so you can help us with it.

I was OK with the context menu, until I wanted to inspect the HTML and couldn't, because of the menu. So I started seeing it as a feature that can be too obstrusive.

As with the layout, yeah, we can create our own theme (probably reuse our current one?): http://sphinx-doc.org/theming.html#creating-themes

Cheers!

__________________________
Diogo Baeder
http://diogobaeder.com.br