Docs? about streamz

[mrocklin]

Docs sound good

…

On Tue, Jul 18, 2017 at 4:25 PM, Christopher J. Wright < ***@***.***> wrote: Any interest in web documentation? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#36>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AASszFiaVrooTU50aypAVY-pq6X9Lxp-ks5sPRS-gaJpZM4Ob4Jw> .

[CJ-Wright]

I'm going to use doctr if that is ok.

[mrocklin]

Why not readthedocs?

[CJ-Wright]

I guess I'm more familiar with doctr. They also enumerate a couple of reasons to use it over readthedocs.

[mrocklin]

Neither of the reasons listed seem very motivating to me:

You are limited in what you can install in Read the Docs. Travis lets you run arbitrary code, which may be necessary to build your documentation.
Read the Docs deploys to readthedocs.io. Doctr deploys to GitHub pages. This is often more convenient, as your docs can easily sit alongside other website materials for your project on GitHub pages.

Some reasons I like readthedocs

• It has been around for a long time and has become something of a standard
• It handles latest and stable versions of documentation, and has nice history about build failures
• It is maintained by dedicated developers

However, if I'm going to push readthedocs then I should probably also be willing to put in some effort to set things up.

I suspect that in both cases we're just going to be pushing rst or md files to a docs/ directory in the master branch, yes?

[CJ-Wright]

Ok, yes if you don't mind I've not used readthedocs before. Yes, both are standard docs/ based things. As a side note one thing that I've been looking at doctr to do is render latex documents for collaborators. This way there is a CI based standard so even if you are missing a library or some other resource you can always get your paper rendered.

[mrocklin]

Ah, right, so it looks like I started down this path before but stopped because I ran into the naming issue. What do we call this thing? A few classes of options:

1. streamspy or some not-yet-taken alternative involving streams and python
2. Some novel name
3. dask-streams (which sort of forces me to make a dask-powered version at some point)

I have a slight inclination towards 3, mostly because it avoids creativity

[CJ-Wright]

I personally like 3, since it means that we might get a dask-powered version at some point (which I'm happy to help out on, its on my todo list but its not so near the top). I know @ordirules was working on getting the streams name on pypi since the existing library seems to be defunct.

[jrmlhermitte]

I contacted the owner of the name by email but no response: https://github.com/ztane. I sent out this email about 2 months ago.
The package has had no activity since over two years ago.

I suggest going higher up. I have not done so, but I could try to ask in pypi if it's possible to change ownership of a library and delete it and start fresh again.

[jrmlhermitte]

I wasn't sure how to go about this, so I asked a general question on the forum. Is there a better way?

[mrocklin]

If we're going with dask-streams then I don't think we need to pursue the streams name

…

On Thu, Jul 20, 2017 at 9:14 AM, Julien Lhermitte ***@***.***> wrote: I wasn't sure how to go about this, so I asked a general question [on the forum] (https://sourceforge.net/p/pypi/support-requests/742/). Is there a better way? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#36 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AASszCpgXFqqqEHkRSO6VoDPyodYNUZQks5sP1KlgaJpZM4Ob4Jw> .

[jrmlhermitte]

ok, great. so where will it land? (dask-streams.github.io ? )

[jrmlhermitte]

Naming discussion moved to #35

[danielballan]

I have alternately used readthedocs and doctr for a couple projects. I think readthedocs is perfectly good for pure-Python projects like dask-streams, and it might be nice to stick with it for consistency with the rest of the dask mini-ecosystem. I would be glad to help with documentation-writing, wherever it lands.

[CJ-Wright]

I'm closing this issue, as it was really about the creation of web docs. However, the push for writing user docs continues!