feat: Add Sphinx Documentation #25

coolalexzb · 2020-07-28T03:26:11Z

This PR aims to add Sphinx documentation for pyhf-benchmark.
The main page of documentation has been completed, and the page looks like as follows:

More contents need to be added into the introduction, examples, etc.

matthewfeickert

This is great to see. I'll enable some extensions that will help with testing Sphinx builds.

matthewfeickert · 2020-07-28T03:40:00Z

docs/source/conf.py

+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["m2r2"]


This is fine for now, but given that m2r2 is a fork of an abandoned project it is probably worth just switching to RST for long term support, which pyhf reluctantly did. That can be for another PR though. 👍

Okay, since I wanted to use README.md directly rather than write README.rst before. I will discard the usage of m2r2 and wrote a README.rst file in the next PR.

Yeah keeping it as Markdown I think is fine for now.

matthewfeickert · 2020-07-28T03:50:59Z

For Sphinx to really be powerful it will need to be able to understand the code though, so it will help to get PR #19 done first.

codecov · 2020-07-30T02:05:04Z

Codecov Report

Merging #25 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master      #25   +/-   ##
=======================================
  Coverage   85.89%   85.89%           
=======================================
  Files          12       12           
  Lines         482      482           
  Branches       67       67           
=======================================
  Hits          414      414           
  Misses         54       54           
  Partials       14       14

Flag	Coverage Δ
#unittests	`85.89% <ø> (ø)`

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

Impacted Files	Coverage Δ
src/pyhf_benchmark/jsonlfile.py	`96.36% <ø> (ø)`
src/pyhf_benchmark/load.py	`100.00% <ø> (ø)`
src/pyhf_benchmark/manager.py	`100.00% <ø> (ø)`
src/pyhf_benchmark/mle.py	`100.00% <ø> (ø)`
src/pyhf_benchmark/plot.py	`89.87% <ø> (ø)`
src/pyhf_benchmark/run.py	`83.90% <ø> (ø)`
src/pyhf_benchmark/stats.py	`66.91% <ø> (ø)`
src/pyhf_benchmark/util.py	`100.00% <ø> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update bc0f912...4883ed0. Read the comment docs.

coolalexzb · 2020-08-14T21:55:37Z

@matthewfeickert Documentation contents have been added and you can enter into docs directory and use sphinx-build -b html source build command to look through the documentation contents.

coolalexzb · 2020-08-17T16:02:38Z

@matthewfeickert What are the further steps for this PR?

matthewfeickert

I need to preview this still and get the ReadTheDocs integration setup but this is looking good overall. Some things need fixing though.

matthewfeickert · 2020-08-19T19:46:50Z

docs/source/conf.py

+xref_links = {"arXiv:1007.1727": ("[1007.1727]", "https://arxiv.org/abs/1007.1727")}
+
+# Github repo
+issues_github_path = "scikit-hep/pyhf/pyhf-benchmark"


Suggested change

issues_github_path = "scikit-hep/pyhf/pyhf-benchmark"

issues_github_path = "pyhf/pyhf-benchmark"

path is wrong

docs/source/development.rst

matthewfeickert · 2020-08-19T19:51:15Z

src/pyhf_benchmark/manager.py

+
+        Returns:
+


Suggested change

Returns:

If no return don't list it.

matthewfeickert · 2020-08-19T19:54:10Z

src/pyhf_benchmark/plot.py

+    Returns:
+


As I mentioned before, probably makes more sense to have the function accept an axis object and then return an axis object then try to wrap all of it, but that can be done for a later PR. At the moment this doesn't return anything so it should get fixed.

matthewfeickert · 2020-08-19T19:54:27Z

src/pyhf_benchmark/plot.py

+
+    Returns:
+
+    """
    fig, ax = plt.subplots()
    ax.set_xlabel("Time (minutes)")


This should probably be seconds not minutes.

matthewfeickert · 2020-08-19T20:07:57Z

None of the required dependencies are setup in a docs extra in setup.py so there is no way to build the docs at the moment if you were a developer who just installed everything. All the requirements need to be listed.

…sphinx

coolalexzb · 2020-08-19T22:29:12Z

@matthewfeickert I created a virtual python environment without any other third-part library installed before successfully, but it is weird that when I use sphinx-build -b html source build command, I can build the docs successfully without any notification that I need to install other libraries.

I changed README.md to README.rst and removed m2r2 extension in conf.py. I think you can try to build the docs again to see if there is any other problem.

coolalexzb · 2020-08-19T22:31:21Z

@matthewfeickert One question in command line api page, the format of command lines in examples are in a mess, can you tell me how to modify it?

coolalexzb · 2020-08-19T22:35:46Z

@matthewfeickert The bug in CI/docs (3.8) still needs to be solved. What is the possible reason?

matthewfeickert · 2020-08-20T00:22:27Z

I created a virtual python environment without any other third-part library installed before successfully, but it is weird that when I use sphinx-build -b html source build command, I can build the docs successfully without any notification that I need to install other libraries.

It seems that you don't actually have a properly isolated virtual environment. If on this branch in a clean virtual environment I get the following

$ python -m pip install --upgrade -e .[complete]
$ python -m pip list | grep "Sphinx\|sphinx"
Sphinx                        3.2.1
sphinxcontrib-applehelp       1.0.2
sphinxcontrib-devhelp         1.0.2
sphinxcontrib-htmlhelp        1.0.3
sphinxcontrib-jsmath          1.0.1
sphinxcontrib-qthelp          1.0.3
sphinxcontrib-serializinghtml 1.1.4
$ cd docs
$ make html
Running Sphinx v3.2.1

Extension error:
Could not import extension sphinxcontrib.bibtex (exception: No module named 'sphinxcontrib.bibtex')
make: *** [Makefile:21: html] Error 2

The bug in CI/docs (3.8) still needs to be solved. What is the possible reason?

If you look at the logs

Run python setup.py build_sphinx
  python setup.py build_sphinx
  touch docs/_build/html/.nojekyll
  shell: /bin/bash -e {0}
  env:
    pythonLocation: /opt/hostedtoolcache/Python/3.8.5/x64
running build_sphinx

Application error:
config directory doesn't contain a conf.py file (docs)
##[error]Process completed with exit code 1.

it tells us the same error as

$ python setup.py build_sphinx
running build_sphinx

Application error:
config directory doesn't contain a conf.py file (docs)

as conf.py isn't at the top level of docs/

$ find . -iname "conf.py"
./docs/source/conf.py

. Why are all the docs under source/? Is this a new recommendation from Sphinx? The first error from make html isn't a surprise though as you have have required the module

$ git grep "bibtex"
docs/source/conf.py:    "sphinxcontrib.bibtex",

but haven't added it to the docs extra

$ git diff origin/master -- setup.py
diff --git a/setup.py b/setup.py
index c8df5b1..1d944ad 100644
--- a/setup.py
+++ b/setup.py
@@ -20,6 +20,7 @@ extras_require["develop"] = sorted(
         + ["check-manifest", "bumpversion~=0.5", "pre-commit", "twine",]
     )
 )
+extras_require["docs"] = sorted(set(["sphinx"]))
 extras_require["complete"] = sorted(set(sum(extras_require.values(), [])))
 
 setuptools.setup(extras_require=extras_require,)

coolalexzb · 2020-08-20T04:51:05Z

@matthewfeickert I use the same command lines as you did but I can still build the doc successfully even I denote a python version as 3.8(which is a different version with the python in my local PC) in virtual environment. As the information from your result. I just need to add to setup.py?
extras_require["docs"] = sorted(set(["sphinxcontrib.bibtex"]))

coolalexzb · 2020-08-20T04:55:59Z

@matthewfeickert If I don't use source file I will get an error when build docs locally. The error information is the same as CI/docs (3.8)

matthewfeickert added the documentation Improvements or additions to documentation label Jul 28, 2020

matthewfeickert assigned coolalexzb Jul 28, 2020

matthewfeickert reviewed Jul 28, 2020

View reviewed changes

matthewfeickert force-pushed the sphinx branch from 1f94889 to bd1552f Compare July 30, 2020 02:01

matthewfeickert force-pushed the sphinx branch from bd1552f to 2380560 Compare July 30, 2020 08:04

matthewfeickert marked this pull request as draft August 15, 2020 00:36

coolalexzb marked this pull request as ready for review August 17, 2020 19:53

coolalexzb added 8 commits August 18, 2020 12:21

Add Sphinx Doc

1d67a04

Clear static

6ccdca7

Update README

839702c

Add Sphinx Doc

09e4be6

Clear static

c9308b4

Add comments

c91e60e

Add cli python API

1645959

Add ipython demo

79e6742

coolalexzb force-pushed the sphinx branch from 6efed93 to 79e6742 Compare August 18, 2020 17:22

matthewfeickert requested changes Aug 19, 2020

View reviewed changes

Add GHA workflow for CI

591532c

matthewfeickert and others added 7 commits August 19, 2020 15:14

Remove doctest of README

ff49ec7

Fix YAML indent

173ac85

Change README style

a3bbd62

Resolve review

e3976f3

Add extra doc

8ec3751

Merge branch 'sphinx' of https://github.com/pyhf/pyhf-benchmark into …

4def1f2

…sphinx

Add doc exts

4883ed0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add Sphinx Documentation #25

feat: Add Sphinx Documentation #25

coolalexzb commented Jul 28, 2020

matthewfeickert left a comment

matthewfeickert Jul 28, 2020

coolalexzb Jul 28, 2020

matthewfeickert Jul 28, 2020

matthewfeickert commented Jul 28, 2020

codecov bot commented Jul 30, 2020 •

edited

Loading

coolalexzb commented Aug 14, 2020 •

edited

Loading

coolalexzb commented Aug 17, 2020

matthewfeickert left a comment

matthewfeickert Aug 19, 2020

matthewfeickert Aug 19, 2020

matthewfeickert Aug 19, 2020

matthewfeickert Aug 19, 2020

matthewfeickert commented Aug 19, 2020

coolalexzb commented Aug 19, 2020 •

edited

Loading

coolalexzb commented Aug 19, 2020

coolalexzb commented Aug 19, 2020

matthewfeickert commented Aug 20, 2020 •

edited

Loading

coolalexzb commented Aug 20, 2020

coolalexzb commented Aug 20, 2020

	issues_github_path = "scikit-hep/pyhf/pyhf-benchmark"
	issues_github_path = "pyhf/pyhf-benchmark"

feat: Add Sphinx Documentation #25

Are you sure you want to change the base?

feat: Add Sphinx Documentation #25

Conversation

coolalexzb commented Jul 28, 2020

matthewfeickert left a comment

Choose a reason for hiding this comment

matthewfeickert Jul 28, 2020

Choose a reason for hiding this comment

coolalexzb Jul 28, 2020

Choose a reason for hiding this comment

matthewfeickert Jul 28, 2020

Choose a reason for hiding this comment

matthewfeickert commented Jul 28, 2020

codecov bot commented Jul 30, 2020 • edited Loading

Codecov Report

coolalexzb commented Aug 14, 2020 • edited Loading

coolalexzb commented Aug 17, 2020

matthewfeickert left a comment

Choose a reason for hiding this comment

matthewfeickert Aug 19, 2020

Choose a reason for hiding this comment

matthewfeickert Aug 19, 2020

Choose a reason for hiding this comment

matthewfeickert Aug 19, 2020

Choose a reason for hiding this comment

matthewfeickert Aug 19, 2020

Choose a reason for hiding this comment

matthewfeickert commented Aug 19, 2020

coolalexzb commented Aug 19, 2020 • edited Loading

coolalexzb commented Aug 19, 2020

coolalexzb commented Aug 19, 2020

matthewfeickert commented Aug 20, 2020 • edited Loading

coolalexzb commented Aug 20, 2020

coolalexzb commented Aug 20, 2020

codecov bot commented Jul 30, 2020 •

edited

Loading

coolalexzb commented Aug 14, 2020 •

edited

Loading

coolalexzb commented Aug 19, 2020 •

edited

Loading

matthewfeickert commented Aug 20, 2020 •

edited

Loading