Repository: scikit-hep/pyhf

Issue:
Schema missing from docs
# Description

Need to use something like [sphinx-jsonschema](https://pypi.org/project/sphinx-jsonschema/) to fix it up.

# Expected Behavior

I was able to navigate to the schemas...

# Actual Behavior

Schemas are gone :o

# Checklist

- [x] Run `git fetch` to get the most up to date version of `master`
- [x] Searched through existing Issues to confirm this is not a duplicate issue
- [x] Filled out the Description, Expected Behavior, Actual Behavior, and Steps to Reproduce sections above or have edited/removed them in a way that fully describes the issue



Discussion:
Additionally, we might want to check if symbolic links can be supported -- or if we can somehow write `conf.py` to always copy over the schema files into the right location every time.
Hi @kratsg ,

I am tracking this issue because it was mentioned in the [HEP-Data "individual pyhf JSON support"](https://github.com/HEPData/hepdata/issues/164#issuecomment-582998142) issue.

It seems that there was a [commit](https://github.com/scikit-hep/pyhf/commit/732827583fb2c2ad747e690805e30e4c8e343e94#diff-e9f950f17198d3d5e3122a44230a09b9L106) where the documentation creation was changed from using the `Makefile`, to not using it. Given that the `Makefile` rule for generating HTML documentation contains the following line of code:
```shell
rsync -r ../src/pyhf/schemas/ $(BUILDDIR)/html/schemas
```

I think that may be the reason why links to any "https://scikit-hep.org/pyhf/schemas/1.0.0/..." are broken.

Do you remember why this line was changed?
Could we change it back?
hi @Sinclert , so this is because the recommended way to build the sphinx docs is not via the Makefile, but via https://github.com/scikit-hep/pyhf/blob/2ba5ec88d3ab27c15e65aaec6bf40a1ae6231b83/.github/workflows/ci.yml#L106-L110

as such - it's been just slightly annoying to migrate this into sphinx correctly.
Is there any particular reason why is not recommended?

I see that in the official Sphinx webpage they address the invocation from a `Makefile`, as _"make life even easier for you"_ ([reference](https://www.sphinx-doc.org/en/master/usage/quickstart.html#running-the-build)).
> I see that in the official Sphinx webpage they address the invocation from a `Makefile`, as _"make life even easier for you"_ ([reference](https://www.sphinx-doc.org/en/master/usage/quickstart.html#running-the-build)).

Docs on this is here: https://www.sphinx-doc.org/en/master/usage/advanced/setuptools.html

We rely on the (semantic) versioning set up, especially for dev-versioning, and it is quite impossible to get this set through a makefile. We need this so we can use `pkg_resources. get_distribution` to grab the correct versions.
It highly depends on how the _"https://scikit-hep.org/pyhf/schemas"_ URL is going to be used, right?

I can think of 2 aspects to consider:

---

1. **Backwards compatibility of links:**
There are some links pointing to URLs like _"https://scikit-hep.org/pyhf/schemas/1.0.0/model.json"_ that are not working right now. That is because of the issue I pointed in [this comment](https://github.com/scikit-hep/pyhf/issues/686#issuecomment-589187261). I don't know the importance of keeping those old links working, you better know, but that is something [sphinx-jsonschema](https://pypi.org/project/sphinx-jsonschema/) is not going to help with. So, there are 2 options:

- **Option A)** Do nothing.
- **Option B)** Add the following line to [this CI step](https://github.com/scikit-hep/pyhf/blob/master/.github/workflows/ci.yml#L110):


    ```shell
    rsync -r src/pyhf/schemas  docs/_build/html/schemas
    ```

---

2. **Schema JSONs format:**
The schema JSON files can be shown in the documentation by adding a _"schemas"_ section to the main index, with different version headers (_1.0.0_, _1.1.0_...) within. The schemas are currently following the _"JSON Pointer"_ notation. Again, I don't know how important it is to show the _"resolved JSON"_ schemas, or if the _"pointer JSON"_ schemas are good enough. So, I can think of 2 options:

- **Option A)** Pointer JSON format:
    - **Advantage:** no need for [sphinx-jsonschema](https://pypi.org/project/sphinx-jsonschema/).
    - **Disadvantage:** no self-contained schemas. (as it was before [the commit](https://github.com/scikit-hep/pyhf/commit/732827583fb2c2ad747e690805e30e4c8e343e94#diff-e9f950f17198d3d5e3122a44230a09b9L106)).

- **Option B)** Resolved JSON format:
    - **Advantage:** The schemas are self-contained.
    - **Disadvantage:** need [sphinx-jsonschema](https://pypi.org/project/sphinx-jsonschema/) extension.

---

It is not clear to me if this issue was opened because of reason 1 (_"Broken links"_), or reason 2 (_"JSONs not appearing in the format you want"_). [Sphinx-jsonschema](https://pypi.org/project/sphinx-jsonschema/) can only help on the second one.

Could you clarify?

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -213,7 +213,7 @@ def setup(app):
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
 #
-html_extra_path = []
+html_extra_path = ['_extras']
 
 # If not None, a 'Last updated on:' timestamp is inserted at every page
 # bottom, using the given strftime format.


Test patch: