New documentation #1474

jules-ch · 2022-02-23T20:11:58Z

This my go to rework the Pint Documentation.

About the theme, we can choose between, they are widely used & offer good reading experience :

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

For the pydata sphinx theme I need to rearrange the toc tree a bit to have a proper Userguide, API Reference, dev guide if we choose it.

jules-ch · 2022-02-23T20:18:43Z

@hgrecco you can build it and tell me what you think.
i've changed some directive to ipython to have better syntax hightlighting & restructured a bit.
You can change the theme to furo by installing it and put html_theme = 'furo' to see this one.

keewis · 2022-02-23T20:45:36Z

I'd also recommend using autosummary to document the API: it creates overview tables that are much easier to read than the output of autodoc directives

jules-ch · 2022-02-23T20:56:06Z

I'd also recommend using autosummary to API: it creates overview pages that are much easier to read than the output of autodoc directives

Thanks for the tip

hgrecco · 2022-02-24T09:19:31Z

@jules-ch I like it a lot. It is clean, with good contrast, readability and tables and code are properly colored. Go for it.

A few things that I have noticed:

The note in the initial page ("One Last thing") is rendered to big.
In FAQ, the list of other packages is not rendered as a list
You can go to the "sections" (Getting started, User Guide, Advanced topics, ...) but nothing or almost nothing is there. It is weird.
Instead of putting stackoverflow, why don't we create a discussion foum within github. This will also serve to remove questions "how do I" from the issue tracker.
It would be good to split up the developer reference.

docs/user/index.rst

jules-ch · 2022-03-02T20:02:38Z

@hgrecco , I'll try to finish & merge new docs next week.
After that I think we can release a new version.

Then code reorganization will follow. What do you think @hgrecco

hgrecco · 2022-03-02T21:05:05Z

Sounds Perfect!

hgrecco · 2022-03-02T21:05:38Z

I am already working in the code reorganization (I will rebase afterwards) just to get a flavor of how it would look like.

jules-ch · 2022-03-02T21:14:38Z

Yeah saw that, just wanted to know how you would like to proceed since it will have an impact on API reference mostly.

keewis · 2022-03-16T15:48:47Z

ping, @jules-ch. Is there anything I can do to help finishing this? Otherwise, should we release now and include the new documentation in the next release? There's a few bug fixes that would be really important to be included in a release very soon.

jules-ch · 2022-05-04T19:16:11Z

Gonna push this next week for the next release at least the new trees & theme & start from there with new contents.

keewis · 2022-08-23T10:09:43Z

@jules-ch, any updates on this? I think this was close enough, and the only thing left to do is to fix the linter job.

jules-ch · 2022-08-23T10:16:03Z

With the reorganization in facets, I need to update conflicts & API reference.
I haven't had much time lately, I'll try to look into it soon.

keewis · 2022-08-23T11:20:39Z

I'll try to look into it soon.

sure, no pressure.

FYI the merge conflicts seem to be pretty small (I'd think the only one caused directly by the facets is two lines in the numpy notebook), and I'd estimate you'd need about 10-15 minutes at most to resolve them.

jules-ch · 2022-09-03T16:11:52Z

Ok this is ready to be merged.

There is still work to be done to have a proper API Reference that we can link in the documentation.

keewis

I have a few questions, but otherwise this looks good to me, and I agree that anything further (like the API docs) can be done in a separate PR

docs/user/performance.rst

jules-ch · 2022-10-05T20:30:24Z

@keewis & @hgrecco if you can make a final review.
API reference is somewhat difficult to address wit the new facets split.
I'll see what I can do after this merge.

I tried to stick to the style of numpy, pandas etc.
They tried to standardize how documentation is splitted.

tell me what you think & I will merge this

https://pint--1474.org.readthedocs.build/en/1474/

hgrecco · 2022-10-05T20:52:16Z

Congratulation for all the awesome work! It looks fantastic. The facets look fine to me ,but I am maybe not the best person to judge as I know perfectly where everything is and why! In any case, I like it a lot.

My only suggestion is if there is room for a code snippet in the main page. What do you think? I usually like to see how it looks at a glance!

andrewgsavage · 2022-10-05T22:17:55Z

The links on https://pint--1474.org.readthedocs.build/en/1474/user/numpy.html#Technical-Commentary are slightly messed up now.

Is there a way to disable intpretting the unit definition code blocks on https://pint--1474.org.readthedocs.build/en/1474/user/defining.html as python code? Seeing 60 and min colored looks off.

To me it seems odd to see 3 topics under "Going further", I think they would fit under advanced topics. Not a big deal though.

There are two pint.facets.numpy in the API reference

hgrecco · 2022-10-06T00:34:20Z

One more thing (sorry) that I just noticed. At the footer I would rather put By the Pint Authors (and if possible a link to the AUTHORS file).

And in Contributing: We do not use travis anymore.

jules-ch · 2022-10-06T08:08:05Z

One more thing (sorry) that I just noticed. At the footer I would rather put By the Pint Authors (and if possible a link to the AUTHORS file).

Ok, I'll make the changes

And in Contributing: We do not use travis anymore.

Yep saw that commit haven't been pushed yesterday xD

keewis · 2022-10-06T09:24:56Z

From a quick glance, this looks good to me. I'd probably fix the the footer and merge afterwards: this change is big enough already, so I think anything further would be easier to review / merge in separate PRs.

The links in the numpy technical commentary have been broken for quite some time (this is a known limitation of nbsphinx), so while I think that we definitely should fix them, I don't think that has to be in this PR. Same with the syntax highlighting of the unit definitions (I think the reason is the use of :: to create code blocks, explicitly using .. code:: might get rid of that?).

As for the facets: those are pretty advanced and most likely only contributors would read it, but I think we should try to create a new page describing the API to help new contributors with understanding the general structure of the code base (but once again, I don't think that should be done in this PR).

jules-ch · 2022-10-09T14:00:40Z

I agree with @keewis. I'll try to fix most of your remarks but we need to get this out & work form there.
I've delayed this for quite some time now :D

- Rework of configuration with new sphinx_book_theme - Use ipython directive where necessary - Add theme to requirements_docs.txt - Start using autosummarry - Fix doctests - Add sphinx design to requirements - Add overview & panels in home page - Update footer with `Pint Developers` - Fix docstrings - Use string imports in __all__ in __init__.py

jules-ch · 2022-10-09T18:59:41Z

I've changed the footer.

I'll wait for CI to finish & I'm gonna merge this. We can have follow up issues/PR.

jules-ch force-pushed the new-documentation branch from 8c75069 to 17ef268 Compare February 23, 2022 20:25

andrewgsavage reviewed Feb 24, 2022

View reviewed changes

docs/user/index.rst Outdated Show resolved Hide resolved

keewis mentioned this pull request Mar 2, 2022

new release? #1450

Closed

21 tasks

jules-ch force-pushed the new-documentation branch from 17ef268 to 1d937f7 Compare September 3, 2022 15:25

jules-ch changed the title ~~Draft: New documentation~~ New documentation Sep 3, 2022

keewis reviewed Sep 4, 2022

View reviewed changes

docs/user/performance.rst Show resolved Hide resolved

docs/user/performance.rst Show resolved Hide resolved

docs/user/performance.rst Outdated Show resolved Hide resolved

jules-ch force-pushed the new-documentation branch from 5967ca2 to b437377 Compare September 18, 2022 10:35

jules-ch force-pushed the new-documentation branch 2 times, most recently from a2cc663 to e0932e0 Compare October 4, 2022 21:30

jules-ch force-pushed the new-documentation branch from 4f5db6d to 6014b35 Compare October 9, 2022 15:46

jules-ch force-pushed the new-documentation branch from 6014b35 to 51d0614 Compare October 9, 2022 18:58

jules-ch merged commit 052a920 into hgrecco:master Oct 9, 2022

jules-ch mentioned this pull request Oct 10, 2022

Improve the docs #972

Closed

dcamron mentioned this pull request Oct 26, 2022

Intersphinx issue #1637

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New documentation #1474

New documentation #1474

jules-ch commented Feb 23, 2022 •

edited

Loading

jules-ch commented Feb 23, 2022

keewis commented Feb 23, 2022 •

edited

Loading

jules-ch commented Feb 23, 2022

hgrecco commented Feb 24, 2022

jules-ch commented Mar 2, 2022

hgrecco commented Mar 2, 2022

hgrecco commented Mar 2, 2022

jules-ch commented Mar 2, 2022

keewis commented Mar 16, 2022 •

edited

Loading

jules-ch commented May 4, 2022

keewis commented Aug 23, 2022

jules-ch commented Aug 23, 2022

keewis commented Aug 23, 2022

jules-ch commented Sep 3, 2022

keewis left a comment

jules-ch commented Oct 5, 2022 •

edited

Loading

hgrecco commented Oct 5, 2022

andrewgsavage commented Oct 5, 2022

hgrecco commented Oct 6, 2022

jules-ch commented Oct 6, 2022 •

edited

Loading

keewis commented Oct 6, 2022

jules-ch commented Oct 9, 2022 •

edited

Loading

jules-ch commented Oct 9, 2022

New documentation #1474

New documentation #1474

Conversation

jules-ch commented Feb 23, 2022 • edited Loading

jules-ch commented Feb 23, 2022

keewis commented Feb 23, 2022 • edited Loading

jules-ch commented Feb 23, 2022

hgrecco commented Feb 24, 2022

jules-ch commented Mar 2, 2022

hgrecco commented Mar 2, 2022

hgrecco commented Mar 2, 2022

jules-ch commented Mar 2, 2022

keewis commented Mar 16, 2022 • edited Loading

jules-ch commented May 4, 2022

keewis commented Aug 23, 2022

jules-ch commented Aug 23, 2022

keewis commented Aug 23, 2022

jules-ch commented Sep 3, 2022

keewis left a comment

Choose a reason for hiding this comment

jules-ch commented Oct 5, 2022 • edited Loading

hgrecco commented Oct 5, 2022

andrewgsavage commented Oct 5, 2022

hgrecco commented Oct 6, 2022

jules-ch commented Oct 6, 2022 • edited Loading

keewis commented Oct 6, 2022

jules-ch commented Oct 9, 2022 • edited Loading

jules-ch commented Oct 9, 2022

jules-ch commented Feb 23, 2022 •

edited

Loading

keewis commented Feb 23, 2022 •

edited

Loading

keewis commented Mar 16, 2022 •

edited

Loading

jules-ch commented Oct 5, 2022 •

edited

Loading

jules-ch commented Oct 6, 2022 •

edited

Loading

jules-ch commented Oct 9, 2022 •

edited

Loading