Improve the docs

[hgrecco]

This is just a placeholder issue to obtain feedback about the current state of the docs:

1. Are the docs clear enough?
2. Are the examples useful and real?
3. Is the information there for a newbie?
4. Is the information there for an advanced user?
5. Is the organization appropiate?
6. What can we do to improve it.

[toihr]

There seems to be an issue regarding the Dataframe Integration

df_ = df.pint.quantify(level=-1)
df_

This Code Snippet given by the Docs does not work and returns the error; 'DataFrame' object has no attribute 'pint'

[toihr]

i just checked more to the Dataframe Integration this part also Produces Errors:

import pandas as pd
import pint
df = pd.DataFrame({
    "torque": pd.Series([1, 2, 2, 3], dtype="pint[lbf ft]"),
    "angular_velocity": pd.Series([1, 2, 2, 3], dtype="pint[rpm]"),
})
df

Produces the error: data type 'pint[lbf ft]' not understood

Im now assuming there is just an import or a setup missing in the Documentation and that fails the Code snippets. Which makes the Pandas Integration part very unintuitive or rather not at all understandable because it is not reproducable.

[jthielen]

Here are some of the thoughts I had (from a high-level perspective, not getting into finer details of the individual pages):

• Content coverage
  • I think the breadth and depth of coverage of material in the docs is pretty good!
  • Perhaps a clearer organization of the user guide into sections (or even just a getting started/user guide/help & reference split like xarray) would be worthwhile
• Navigation
  • I wish there was a better sidebar menu so that you didn't have to jump back to the homepage, click through multiple sections, or use search to navigate and browse the docs
• Small-screen friendliness
  • Right now, the pages are somewhat hard to use on a mobile device or restricted screen width (lack of good top menu, content overflowing device width, etc.)
  • The "Fork me on GitHub" corner banner gets in the way
  • The search experience is especially poor
• API Reference
  • The current API reference, the "Developer Reference" page https://pint.readthedocs.io/en/latest/developers_reference.html is somewhat difficult to use (with its current state, I find it easy to just refer to the source code itself than use that portion of the docs)
  • The formatting does not establish a clear separation between components, and the lack of a summary view makes it hard to browse
  • Not sure what is considered public vs. private API?
  • The testsuite seems to be injected into the reference, which I don't think should happen?
  • Ideally, I'd like to see something like xarray or MetPy with clear summary tables that could then be clicked on for more details.
    • While likely tedious, overall improvement of the docstrings would also greatly help here too

I think many of these could be benefited by changing to a new theme, like the very commonly used Sphinx RTD theme (used by xarray, Dask, CuPy, MetPy, and many others). Would that be a reasonable first step?

[toihr]

i second the sidebar menu that would be a great addition

[hgrecco]

Regarding Navigation and Small-screen friendliness, I think we just need to use another template. This current one has been with us from the very beginning and it has serve us well. But we need to change. My only requirement is that we keep the pint of beer.

Regarding API Reference: 100% agree

Regarding issues raised by @Meistermagier, I think we need to use doctest in combination with travis more extensively. Additionally, it would be good to test the jupyter notebooks that we might upload.

[TomNicholas]

Just echoing what others have said, especially regarding the API reference. The formatting is hard to read, it doesn't have subsections, the [source] links to a copy of the code on the site rather than to the GH, and the test classes shouldn't be listed.

There should also be a better page index on the left of the docs, at the moment you have to scroll to the bottom of the homepage to find anything.

That said I think apart from that the docs are nice, the tutorial sections and descriptions in particular are really good! (Which is the most important part I think).

[jules-ch]

I'm gonna tackle this soon.

I'll probably change the theme for either pydata-sphinx-theme (numpy, pandas, ...) or sphinx_book_theme (xarray) which is based on pydata theme.

It will leverage a better experience & I know a bunch of contributors has experienced with this.

We'll get better side bars to navigate in the docs. I'll also introduce a better API Reference which we lack at the moment.

[keewis]

for some additional reference and help: https://diataxis.fr/ (formerly https://documentation.divio.com)

[keewis]

originally posted in https://github.com/hgrecco/pint/pull/1375#issuecomment-903120313 by @hgrecco:

How about dividing the index? It seems too crowded. This is a proposal

Getting started
    Installation
    Tutorial

User Guide
    Defining Quantities
    String formatting
    Temperature conversion
    Logarithmic Units

Rolling your own conversions and making a better use of those included (find a short title)
    Defining units
    Different Unit Systems (and default units)
    Contexts

Interaction with other packages
    NumPy Support
    Serialization
    Plotting with Matplotlib
    Pandas support

Other cool stuff (find a title)
    Buckingham Pi Theorem
    Optimizing Performance
    Wrapping and checking functions
    Using Pint for currency conversions
    Using Measurements (I want to extract measurements to another package, and then this will go to Interaction with other packages)

More information
    Command-line script
    Developer reference
    Contributing to Pint
    Frequently asked questions

Edit: Also, I support reorganizing the API reference. I'm not sure whether that's typical usage, but I usually look for the public API in the docs and when working on pint I just look through the source code. In any case, in my experience autosummary (without :recursive:, if that's the right option) has been pretty easy to work with

[dalito]

I like the proposed structure. I would just move the "Wrapping and checking functions" to section 3. As small title for this section I suggest "Adjusting and integrating pint". So section 3 would target the advanced user.

I find the sub-title "Other cool stuff" OK for a section that describes the features that are not part of the core functionality of a unit library.

"Optimizing Performance" could also fit in section 3 (or in "More information"). It does not fit to "Cool stuff".

[hgrecco]

I also think that the tutorial could be rewriten. For example:

• Localizing, I think it could be moved to another section. Either within String formatting or a new one inside Interaction with other packages
• The string parsing and formatting subsection sould be more focus and a link to the corresponding expanded section

[jules-ch]

Closing this after #1474