Documentation for Reflex

[dfordivam]

Have a look at this link for a hosted version of this pull-request.
http://reflex-frp.readthedocs.io/en/latest/

This documentation is now in a shape where you can add content. (especially @mightybyte , @ryantrinkle you guys should have lots of things to add...)

Also I have added some code snippets in this PR. I have referenced some of them in documentation, and some I have inlined completely.

[mightybyte]

This look amazing!

[mightybyte]

We should set things up so that all the code snippets are compiled by the test suite.

[ryantrinkle]

@mightybyte Great idea! Added here.

[ryantrinkle]

@dfordivam This is really fantastic. How should we go about hosting this more permanently? Perhaps it'd make sense to put it at docs.reflex-frp.org, with a redirect from reflex-frp.org until we've got a real homepage to put there?

[ali-abrar]

@dfordivam this looks like a good start. Thanks for taking the lead on this.

I'm still reading through it, but one thing that occurs to me from the outset is that the "Architecture of a Reflex Application" section seems primarily focused on the architecture of reflex-dom applications, and we might want to make that clearer in the title and introductory text.

[mulderr]

Nice job. One nitpick I found, the WebSockets section could use a clarification about the reconnect behavior. I was meaning to put a note somewhere but there wasn't really a good place ;)

Manually closing a websocket that is configured to reconnect will cause it to reconnect. If you want to be able to close it permanently you need to set _webSocketConfig_reconnect = False.

Regarding route sharing, I guess people have their own better solutions but since they're not public I wrote this some time ago. It's mostly Generic (pun intended). Also, too long, not reviewed at all and I'm not super happy with it but if anyone wants to use parts of it, go ahead.

[dfordivam]

@ali-abrar Hello!

[dfordivam]

@ryantrinkle sounds good. To keep the setup simple we can use the readthedocs for hosting, by supplying the domain name. (https://docs.readthedocs.io/en/latest/alternate_domains.html)

Another benefit here is that if you push on github the docs will get updated automatically.
(I can set the readthedocs to track the master branch of reflex-frp/reflexfrp.org once we merge the PR)

[dfordivam]

I just realised that github supports rst editing also. We can directly edit the documentation in browser and preview it!

[katychuang]

@dfordivam great job on this so far and thanks for taking initiative on this!

I was invited to provide input so here are my thoughts....

Documentation on this library has been sorely needed since inception, and despite the fact that any docs would be thirst quenching - the readability and thoroughness of content in these set of docs surpasses expectations. From what I've skimmed so far it is accessible to novices and code snippets also easy to follow. I'll make a more careful reading pass soon and comment on editorial changes then.

The workflow sounds good also. Keeping the source on github and hosting on readthedocs, indirectly provides a benefit of being easier for the public to find in both systems 😄

As far as the domain, my preference is setting up redirects from: (1) docs.reflex-frp.org, and/or (2) reflex-frp.org/docs rather than the main root url for number of reasons.. proper semantics for SEO, and also in the future bookmark are more precise. My mental model is based on the assumption that reflex-frp.org will contain links to other sections such as examples, tutorials, plugins, contribution/community, etc. As a concrete example, if reflex-frp moves onto other languages, maybe getting a little bit of myself here however, docs would then be a more specific route. Since the (sub)domain is easily changed I'm not married to the route patterns right now so long as it's easy for folks to find the content.

Hooray on a great start and moving towards a major milestone in reflex-frp history 🎉

[ryantrinkle]

@dfordivam Thanks! I just set up the CNAME to point docs.reflex-frp.org to reflex-frp.readthedocs.io. Could you add me to the project on readthedocs?

[ryantrinkle]

@katychuang I think it's easier at the moment to use a subdomain than a subdirectory, so I've set it up that way for now; happy to change it later if that becomes necessary. Thanks for taking a look at this stuff and helping move it along!

[dfordivam]

@ryantrinkle did you get the access?

[ryantrinkle]

@dfordivam Yep, and I was able to set docs.reflex-frp.org as the canonical domain. Thanks!