Doc plans

[andrewgsavage]

Here's a discussion for longer term doc plans.

1. The theme looks a little dated. Is there any interest in moving to another theme?

The widely used options are:

• furo (urllib3, black, pip, psycopg3)
• sphinx-book-theme based on pydata sphinx theme (xarray)
• pydata-sphinx-theme (scipy, numpy, pandas)

pydata-sphinx-theme requires would need a bit of work to rearrange the current doc into pages for a tutorial, API reference... Which leads to my next Q:

2. The user guide is quite long for a new user to read through all of it. I'd suggest a shorter, condensed tutorial with more detail moved to dedicated pages. Any thoughts on this?

3. What pages would you like to see? I can imagine pages for:

• Contributing
• Covariance and correlation matrices + Correlated variables
• Formatting
• Theory (Linear propagation of uncertainties, Mathematical definition of numbers with uncertainties,

[newville]

See also #203.

1. The theme looks a little dated. Is there any interest in moving to another theme?

I have no objection to changing the theme or real love of the current one. But what does "a little dated" mean? Should the theme be changed regularly?

The widely used options are:

furo (urllib3, black, pip, psycopg3)

My knee-jerk reaction is always: "If black is involved, I am walking away". I cannot think of a more loathsome project or even a concept in the Python ecosystem that is as utterly evil and contemptible as black. So, sorry "furo" theme, you did nothing wrong but "black" apparently picked you, so this one gets a -1 from me. I am willing to volunteer my time to work on these docs. If furo is the theme, my willingness to do that will end.

sphinx-book-theme based on pydata sphinx theme (xarray)
pydata-sphinx-theme (scipy, numpy, pandas)

No preference or opposition. Are there advantages to either of these themes? Like, do they offer features that are useful to us?

The user guide is quite long for a new user to read through all of it. I'd suggest a shorter, condensed tutorial with more detail moved to dedicated pages. Any thoughts on this?

Yes, I think this could be shorter. I shortened the "install and about" some, and started working on shortening "user guide" too. I would suggest it be recast as "Getting Started" (basic ufloats and umath) and then more advanced topics. That is, there is more to do.

What pages would you like to see? I can imagine pages for:

Contributing

Maybe just a link to GitHub is enough? Or do you mean something more?

Covariance and correlation matrices + Correlated variables

Yes.

Formatting

Probably. I feel like formatting is a separate topic. There is quite a lot of emphasis and code and docstrings in core.py concerned with formatting. I would vote for a separate formatting.py module, and maybe scaling this back. Yes, include the PDG 2010 recommendation for how many digits to show. But also, let's allow this to be done elsewhere (sciform) and be less imposing about what formatting is permitted (see also: black is evil).

Theory (Linear propagation of uncertainties, Mathematical definition of numbers with uncertainties,

Maybe. Or maybe this can be referenced away?

[andrewgsavage]

Dated meaning that it looks like it's 10 years old (which it is!) I'm not aware of major new features. Sharing a theme with other widely used modules gives a familiar look. The pydata one requires a tutorial/getting started, and encourages subpages under sections. I found smaller pages slightly more navigatable when pint switched

…

On Tue, 23 Apr 2024, 03:57 Matt Newville, ***@***.***> wrote: See also #203 <#203>. 1. The theme looks a little dated. Is there any interest in moving to another theme? I have no objection to changing the theme or real love of the current one. But what does "a little dated" mean? Should the theme be changed regularly? The widely used options are: furo <https://pradyunsg.me/furo/quickstart/> (urllib3, black, pip, psycopg3) My knee-jerk reaction is always: "If black is involved, I am walking away". I cannot think of a more loathsome project or even a concept in the Python ecosystem that is as utterly evil and contemptible as black. So, sorry "furo" theme, you did nothing wrong but "black" apparently picked you, so this one gets a -1 from me. I am willing to volunteer my time to work on these docs. If furo is the theme, my willingness to do that will end. sphinx-book-theme <https://sphinx-book-theme.readthedocs.io/en/latest/index.html> based on pydata sphinx theme (xarray) pydata-sphinx-theme <https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html> (scipy, numpy, pandas) No preference or opposition. Are there advantages to either of these themes? Like, do they offer features that are useful to us? The user guide is quite long for a new user to read through all of it. I'd suggest a shorter, condensed tutorial with more detail moved to dedicated pages. Any thoughts on this? Yes, I think this could be shorter. I shortened the "install and about" some, and started working on shortening "user guide" too. I would suggest it be recast as "Getting Started" (basic ufloats and umath) and then more advanced topics. That is, there is more to do. What pages would you like to see? I can imagine pages for: Contributing Maybe just a link to GitHub is enough? Or do you mean something more? Covariance and correlation matrices + Correlated variables Yes. Formatting Probably. I feel like formatting is a separate topic. There is quite a lot of emphasis and code and docstrings in core.py concerned with formatting. I would vote for a separate formatting.py module, and maybe scaling this back. Yes, include the PDG 2010 recommendation for how many digits to show. But also, let's allow this to be done elsewhere (sciform) and be less imposing about what formatting is permitted (see also: black is evil). Theory (Linear propagation of uncertainties, Mathematical definition of numbers with uncertainties, Maybe. Or maybe this can be referenced away? — Reply to this email directly, view it on GitHub <#220 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADEMLEHI3UUF4TM44DFLLW3Y6XEYFAVCNFSM6AAAAABGTWNJ4GVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TCOJVGY3TI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[newville]

I made a few more tweaks to the docs in PR #203. The interim result at https://lmfit.github.io/uncertainties/ currently uses the python_docs theme. I also sort of like the bizstyle rendering.

I found that pydata-sphinx did want a different layout of content and that the current set of docs didn't seem to fulfill all the needs (like it didn't fill out both left and right-hand sidebars). I'm not opposed to adopting this or similar theme, but it seems like this requires learning and committing to a new theme. For now, I'm just trying to clean up the content (and finding that challenging enough!). Any suggestions or help would be greatly appreciated.

As I go through this, I'm not really sure we even need to call a section "User Guide" and another section "Technical Guide". That is, the basic interface can be explained in few paragraphs, and then there are a series of additional topics, many of which can be digested out-of-order, though some might refer to other sections. For sure, it is okay to bury more complicated topics (using correlated_variables(), pickling).

I might suggested "Getting Started", and then a longer "Advanced Topics".

[andrewgsavage]

I'd opened this discussion as it'd be more of a long term thing to look at changing. I wasn't expecting you to make a start at it in your PR already! Yea cleaning the content should be the priority.

...
I might suggested "Getting Started", and then a longer "Advanced Topics".

That would work nicely

[newville]

@andrewgsavage Thanks -- and, yes I do get that there is a difference between the "immediate" (3.2.0?) goal and the long-term goal.

My limited experience withpydata-sphinx is that it is worth exploring, but I'd put it in the "long term category".

FWIW, I do not think #203 is done, but happy to have any feedback... so thanks!