Documentation overhaul

[dmdunla]

Evolving the documentation incrementally in the way we have been doing in the past few merges seems to be causing challenges to progressing on overall development (e.g., I'd like to release a new patch version to support several users but I do not want to release the documentation in a mid-revision state). This is my fault, and I take full responsibility. I had thought the doc change requests were relatively minor, but as the discussion has progressed, I see that it is more complicated in several ways.

I'd like to move documentation aside from the main development, creating a new branch dedicated to a comprehensive documentation overhaul that would then be merge altogether into a new minor release (rather than as patches as we have been doing).

Here are some things that we should discuss and work on to come to a useful set of docs:

1. Who is the audience of the RTD docs?

• My suggestion is the end user. We could provide more docs for developers, but I believe this is a lower priority right now. And I do not want to conflate the two in a single set of docs.

2. How do we want to document a class?

• My suggestion is to follow conventions used by other (major) Python packages that users of pyttb might use -- e.g., numpy, scipy, pandas.
• This includes some standardization of the class doc format, too.
• This includes determining which methods to include -- e.g., dunder (__foo__), internal (_bar), and helper functions included in module files but not specified as methods of the main class defined in that module file.

3. What are the entry points we expect for documentation?

• readthedocs.io
• help(pyttb)
• Reading through the source code

4. What should the interplay between the docs and the tutorial be?

• Are there different audiences for these?
• How should we align content/examples/tests?

[tgkolda]

@dmdunla - I'm happy to do whatever you'd like.

I don't think these changes should have impact on overall development, especially in bits and bites. I'm curious what obstacles you're encountering?

1. Yes, the end user. That's my target, and I think the things I'm flagging in the documentation are all related to the end user. Can you give me an example of something that wasn't?

That said, developers also need documentation.

2. It's not all that easy to follow the conventions of these other packages as they have much more extensive documentation based on custom pages rather than automatic generation from source code. I would also suggest some clarify on class versus namespace and what should or shouldn't be lifted to the pyttb namespace.

I would be happy to follow any guidelines you'd like to establish and/or to help in developing such guidelines. I've generally been of a mind to just evolve those as one goes.

3. As to entry points, I would also add IDE pop-ups.

4. I think of both as documentation, but I guess you're talking about function-level documentation. This should be the reference for someone using a function, with a description and examples of the common usage. More complicated examples go into more extensive documentation. These might be "tutorials" or just other documentation that goes into more details than the function help. I think of tests as separate, myself. The documentation and tutorial do a bit of testing because they have to run, but they are not extensive.

[tgkolda]

I'm not sure what you mean by the following: "We could provide more docs for developers, but I believe this is a lower priority right now. And I do not want to conflate the two in a single set of docs."

For example, numpy has everything in one. There is a section for contributing, and it's part of the overall documentation. Does that fit the model you envision?