Improve documentation

[xmnlab]

Would be good to improve documentation the documentation to improve user and developer experience.

Topics to improve:

• Special topics that deserve detailed documentation. E.g: Ragged arrays ( var(offsets))
• Guidelines on how to extend xnd/gumath and how to use it as a back-end library
• Guidelines on how to contribute to plures projects
• Keep a list of projects using xnd as a backend library (e.g: https://github.com/Quansight/xndframes) or xnd's extensions (https://github.com/Quansight/numba-xnd) on xnd's website so that they can be used as reference for developers.
• More Ideas/suggestions of what needs to be done to improve the documentation

Extra topics:

• Improve tests including conda packaging
• Triage of issues and maybe a wish list of features that need to be implemented
• Add code coverage

[saulshanabrook]

I was just thinking I would like to add a little blog somewhere so we can talk about xnd. Even if it was just a slightly elaborated version of our meeting notes that we have once a week, I think it would be useful for others who are new to the project to see where development is going.

I like Dask's website https://dask.pydata.org/en/latest/ because it seemlessy transitions between the intro page and the read the docs. Could we replicate this in some way? Goals I see:

• Make it easy for users to navigate between docs of all projects
• Should be able to get to landing page easily, right now none of the docs link to xnd.io
• On landing page, have intro, examples, blog posts.

Thoughts?

[saulshanabrook]

I think the Rust (the game) project has a very nice developer blog, see: https://rust.facepunch.com/blog/the-team-update/ They make it interesting and fun to follow their work even if you are not using their project (playing their game). I think we could do the same. Simplest way to do this might be to add jekyll auto generation to website repo, so we could write posts in markdown and have them posted. I am happy to help set this up.

[xmnlab]

@saulshanabrook

I like that! I think we could do that. if we have at least one blog post each week .. it will be very interesting.

I don't have experience with jekyll but I can learn and help you with you want.

should we schedule a meeting just for documentation tasks?

[xmnlab]

cc @andersy005 @davidbrochart ^^^

[saulshanabrook]

Yeah that would be great. This week is kinda busy for me since I am at scipy, but next week I'm free 9-5 generally EST

…

On Thu, Jul 12, 2018, 2:56 PM Ivan ***@***.***> wrote: @saulshanabrook <https://github.com/saulshanabrook> I like that! I think we could do that. if we have at least one blog post each week .. it will be very interesting. I don't have experience with jekyll but I can learn and help you with you want. should we schedule a meeting just for documentation tasks? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#22 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABIZTKLRJk2rK6Rr_YydqjiuFT5bKErLks5uF6ndgaJpZM4VLJac> .

[xmnlab]

notes from last meeting (2018-07-16):

• ndtypes and datashapes should be similar docs.
• create blog jekyll
• put the notebooks inside read the docs.
• xnd/ndtyeps/gumath
• developer guideline (start point https://github.com/plures/xndtools/blob/master/doc/notes/notes1.rst)
• use git subtree, use single command to build single library
• tutorial add extra types float66
• examples extending xnd, operations and kernels (gumath)
• add kenerls outside from gumath, extension module
• create documentation for xndtools
• gumath, xnd, ndtypes should be connected
• create text about the relation about gumath/xnd/ndtypes (could use dask as reference)
• maybe create a readthedocs inside the same url like url/lib
• add more numpy api functions/attributes to xnd_gumath class

[wesm]

I have mentioned it elsewhere, but since xnd and gumath are inseparable from ndtypes, why not develop in a single git repository? Some people might be discouraged from contributing if patches might require multiple simultaneous changes across different repos. The GitHub UI and development workflow doesn't accommodate this very well in my experience. Less build / CI infra to maintain, one issue tracker instead of many, etc.

[skrah]

I think that is a good proposal. I'd like to do the merging myself so that the history stays intact.

[skrah]

@wesm @shoyer After some internal discussions we thought that ndtypes should be kept as a separate upstream package for now.

However, I've merged all packages as git subtrees into https://github.com/plures/xnd-all .

So, trying out everything just requires a single python3 setup.py develop or python3 setup.py install.

Contributing of course still requires pull requests to the individual libraries in theory, but personally I would also be happy with diffs attached to an xnd-all issue that cover multiple libraries.

[wesm]

Cool, sounds good.

In the interest of building an inclusive developer community I would advise you to consider limiting "internal discussions" and having discussions like these in a public setting.

https://producingoss.com/en/setting-tone.html#avoid-private-discussions

[skrah]

This is a good link, I agree about public discussions. "Internal" was misleading, the discussion was actually on public Gitter. I think I still only recognize archived mailing lists as really public, hence the mistake. :)

[wesm]

Ah, good to know. Unfortunately systems like Slack and Gitter are harming public discourse in this way; it's hard to find relevant discussions with internet searches =/