Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add section for tutorial and docs to README #1789

Merged
merged 5 commits into from
Feb 25, 2022
Merged

docs: Add section for tutorial and docs to README #1789

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f8f45be
docs: Add section for tutorial to README
matthewfeickert Feb 24, 2022
8cdd4fa
Add user guide section
matthewfeickert Feb 24, 2022
f92c5fa
Sync language with .github/ISSUE_TEMPLATE/config.yml
matthewfeickert Feb 24, 2022
329f4bc
Add section for docs
matthewfeickert Feb 25, 2022
55a3cb1
Fix spelling error
matthewfeickert Feb 25, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ pure-python fitting/limit-setting/interval estimation HistFactory-style

|GitHub Project| |DOI| |JOSS DOI| |Scikit-HEP| |NSF Award Number|

|Docs from latest| |Docs from master| |Binder|
|Docs from latest| |Docs from master| |Jupyter Book tutorial| |Binder|

|PyPI version| |Conda-forge version| |Supported Python versions| |Docker Hub pyhf| |Docker Hub pyhf CUDA|

Expand All @@ -32,6 +32,14 @@ to support modern computational graph libraries such as PyTorch and
TensorFlow in order to make use of features such as autodifferentiation
and GPU acceleration.

User Guide
----------

For an in depth walkthrough of usage of the latest release of ``pyhf`` visit the |pyhf tutorial|_.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm trying to sync language here

$ git grep 'in depth walkthrough'
.github/ISSUE_TEMPLATE/config.yml:    The pyhf tutorial is continually updated and provides an in depth walkthrough
README.rst:For an in depth walkthrough of usage of the latest release of ``pyhf`` visit the |pyhf tutorial|_.

but happy to change it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks fine to me.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was wondering whether it also makes sense to directly link the readthedocs here? The tutorial does so in the first line. It is also in the questions section in the readme as well as in the badges, but both of those are slightly more hidden compared to this new entry. A user will definitely find it regardless, but the benefit I see from also linking the RTD here is that they can be contrasted a bit so a user knows which website is more appropriate for their specific needs.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's a good idea. I put it lower down so that a reader would be hit first by the user guide, then by examples, and then by the docs. Very happy for other thoughts here though. 👍

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No strong opinion here, I think it is fine as-is. I personally think that the "What does it support" section is expert-level material, and that there is a lot of scrolling needed to get to the docs section, but ultimately it is just personal opinion. Users should be able to comfortably find what they are looking for with the layout implemented here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I agree with you here. 👍 As that will take more thought then I think I have in me now, I've bumped that to Issue #1791.


.. |pyhf tutorial| replace:: ``pyhf`` tutorial
.. _pyhf tutorial: https://pyhf.github.io/pyhf-tutorial/

Hello World
-----------

Expand Down Expand Up @@ -261,6 +269,14 @@ To uninstall run

python -m pip uninstall pyhf

Documentation
-------------

For model specification, API reference, examples, and answers to FAQs visit the |pyhf documentation|_.

.. |pyhf documentation| replace:: ``pyhf`` documentation
.. _pyhf documentation: https://pyhf.readthedocs.io/

Questions
---------

Expand Down Expand Up @@ -344,6 +360,8 @@ and grant `OAC-1450377 <https://www.nsf.gov/awardsearch/showAward?AWD_ID=1450377
:target: https://pyhf.readthedocs.io/
.. |Docs from master| image:: https://img.shields.io/badge/docs-master-blue.svg
:target: https://scikit-hep.github.io/pyhf
.. |Jupyter Book tutorial| image:: https://jupyterbook.org/_images/badge.svg
:target: https://pyhf.github.io/pyhf-tutorial/
.. |Binder| image:: https://mybinder.org/badge_logo.svg
:target: https://mybinder.org/v2/gh/scikit-hep/pyhf/master?filepath=docs%2Fexamples%2Fnotebooks%2Fbinderexample%2FStatisticalAnalysis.ipynb

Expand Down