Doc plans #220
Replies: 3 comments 2 replies
-
See also #203.
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?
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.
No preference or opposition. Are there advantages to either of these themes? Like, do they offer features that are useful to us?
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.
Maybe just a link to GitHub is enough? Or do you mean something more?
Yes.
Probably. I feel like formatting is a separate topic. There is quite a lot of emphasis and code and docstrings in
Maybe. Or maybe this can be referenced away? |
Beta Was this translation helpful? Give feedback.
-
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:
***@***.***>
|
Beta Was this translation helpful? Give feedback.
-
I made a few more tweaks to the docs in PR #203. The interim result at https://lmfit.github.io/uncertainties/ currently uses the I found that 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 I might suggested "Getting Started", and then a longer "Advanced Topics". |
Beta Was this translation helpful? Give feedback.
-
Here's a discussion for longer term doc plans.
The widely used options are:
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:
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?
What pages would you like to see? I can imagine pages for:
Beta Was this translation helpful? Give feedback.
All reactions