docs: basic sphinx docs

[APN-Pucky]

Here is something I quickly copied together. To view you can just run in docs make html and view xdg-open build/html/index.html

• CI (=> look at other scikit-hep)
• github pages? (=> look at other scikit-hep)
• scikit-hep RTD? (=> look at other scikit-hep)
• citations list (cf. docs: Add list of pylhe citations #181) -> Best put it at bottom of README.md, since then it is also in the landing pages of the docs.
• Cleanup docs dependencies and sphinx-extensions
• The documentation of the meaning of individual fields would benefit from transition from dict to dataclass? #303 => version 1.0.0 release
• fix warnings/errors shown on make html
• sphinx-napolean layout/design?

Closes: #30
Closes: #181

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.10%. Comparing base (4554bae) to head (2349da5).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #304   +/-   ##
=======================================
  Coverage   95.10%   95.10%           
=======================================
  Files           2        2           
  Lines         347      347           
  Branches       63       63           
=======================================
  Hits          330      330           
  Misses         10       10           
  Partials        7        7           

Flag	Coverage Δ
unittests-3.10	95.10% <100.00%> (ø)
unittests-3.11	95.10% <100.00%> (ø)
unittests-3.12	95.10% <100.00%> (ø)
unittests-3.13	95.10% <100.00%> (ø)
unittests-3.9	95.10% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[eduardo-rodrigues]

Hi @APN-Pucky. For a quick put-together this is already a major improvement! Congrats.

I did not look at everything in detail but did build the docs locally (after installing a lot of stuff in my new-ish laptop - amazing how much one installs over the years, and forgets when getting a new machine!). There are several warnings but that's not issue given that this is still Draft.

I quick like the sophisticated type of docs pyhf has at https://scikit-hep.org/pyhf/ for the HEAD version and at https://pyhf.readthedocs.io/ for docs of tags. We do not need to have documentation so fancy straightaway but the idea of configuring in these 2 sites is great IMHO.

I see that expanded on the examples. Cool! I would take the opportunity to list and organise examples from basics to more sophisticated (see https://pyhf.readthedocs.io/en/v0.7.6/examples.html).

Let's see also what @matthewfeickert feels about this.

[APN-Pucky]

I see that expanded on the examples. Cool! I would take the opportunity to list and organise examples from basics to more sophisticated (see https://pyhf.readthedocs.io/en/v0.7.6/examples.html).

I don't think they are sorted in your link, but I sorted ours by prefixing the ipynbs with a number.

[APN-Pucky]

@eduardo-rodrigues I don't know how/where to set the HEAD output to https://scikit-hep.org/pylhe, but the github-pages CI from pyhf passes.

[eduardo-rodrigues]

Hi @APN-Pucky, you have to go to settings -> pages on the repo to set things up, see for example https://github.com/scikit-hep/hepstats/settings/pages.

We could also do a test build, see scikit-hep/scikit-hep.github.io#421 (our case is simpler since no need for Ruby).

[APN-Pucky]

Hi @APN-Pucky, you have to go to settings -> pages on the repo to set things up, see for example https://github.com/scikit-hep/hepstats/settings/pages.

I can't see that, but I enabled deploy from action now. It also knew about using the scikit-hep.org URL already.

We could also do a test build, see scikit-hep/scikit-hep.github.io#421 (our case is simpler since no need for Ruby).

The CI already builds the docs and uploads it here https://github.com/scikit-hep/pylhe/pull/304/files#diff-9cf2000c53760d837a449f874e53f792819108d3a4bf346336d0f7d082deae2cR75-R78 and you can download the docs html here as (now expired) artifact https://github.com/scikit-hep/pylhe/actions/runs/17130506213.

[eduardo-rodrigues]

Shall I set things in https://github.com/scikit-hep/pylhe/settings/pages myself? You would have see something like

I got the HTML and can have a look during the week. Did you check it's rendering things OK?

So this PR is now ready for review?

Great work/enhancement!

[APN-Pucky]

Shall I set things in https://github.com/scikit-hep/pylhe/settings/pages myself?

Feel free to modify, but I think we use another method than hepstats. I set it up like pyhf to deploy from action and not from the gh-pages branch. I.e. pyhf does not have a gh-pages branch, while hepstats does.

I think not polluting the branch with docs is better.

Did you check it's rendering things OK?

yes.

So this PR is now ready for review?

yes!

[eduardo-rodrigues]

This is looking excellent!

I still just need to look at the latest artifacts, which I will do asap.

[eduardo-rodrigues]

The artifacts look good to me!

[eduardo-rodrigues]

Feel free to merge when also happy. I don't think Matthew is available at present (and this PR started over a month ago).

[APN-Pucky]

Feel free to merge when also happy. I don't think Matthew is available at present (and this PR started over a month ago).

Ok, let's see if the page is available right away or if it needs some CI fixes. Then I'll release 0.9.3. (To include the memory fix in a 0.9 release).

Thanks!

[APN-Pucky]

It is live already here https://scikit-hep.org/pylhe/. Do we have to adjust some scikit-hep link to point to there now? e.g. https://scikit-hep.org/packages/ could have a docs button. Do we enable a page on readthedocs like https://hepstats.readthedocs.io/en/latest/? Technically, I can add it using my RTD account, but maybe it should be done by some scikit-hep RTD-account?

[eduardo-rodrigues]

Correct - that packages page and also https://scikit-hep.org/documentation/. This should all be done via the package YAML, I believe ...

I don't think we have an org account for RTD and maintainers are using their personal ones. But let me check with @henryiii.

As I suggested some time ago in our exchanges, we should use RTD for the tag versions. That's by default anyway, right?

Thanks.