Documentation plan

[gordonwatts]

As a user I want a place to go to learn a lot about ServiceX and using it

Approach

Tools

• Use Jupyter Book to put together a small multi-page doc site
• Send to readthedocs

Target Audience

• Heard of services but not used it
• Wants to extract data from flat ntuple or from xAOD

What should the book contain

• Intro, including where to go to register
• Simple TCut usage
• Simple func_adl usage
• Complex func_adl usage
• Use with coffea
• qastle direct usage
• How to dump something to qastle (to get the qastle string back)
• The web API and examples (e.g. not using the front end)
• front-end services module API reference (??)

Possible Future Topics

These would become new issues that we could write up later on.

• Converting your ntuple maker to use servicex
• Reproducability

To Do

• [ ] Figure out where to locate this
• [ ] Write up book structure
• [ ] Turn the above into issues to be worked on.

[AndrewEckart]

One great example of documentation that I like to refer back to is numba. Observe that it's organized into sections for users and developers. The user section consists of two parts:

• A user manual, which has pages dedicated to common topics
• A reference manual, which exhaustively documents the API I think many of the topics @gordonwatts mentions above would be good for a user manual.

As for notebooks, I think they should supplement documentation, but not replace it. Numba uses a dedicated page for tutorials, but we could also consider writing a documentation page for each topic (e.g. complex func_adl usage) and then linking a notebook at the end with examples. Alternately, there is a fancy tool called nbsphinx which enables Sphinx to take a notebook and generate documentation from it.

[gordonwatts]

@AndrewEckart - this is the tool we've been thinking of using for this: https://jupyterbook.org/intro.html