Docson dependency & reference resolution

[timgdavies]

(I'm not sure if this best belongs as part of the theme, or as part of the docs repo: but putting here to avoid it getting lost amongst standard issues)

We use docson as a schema viewer.

At present this is a sub-module in the docs /_static/ folder.

The version we use does not have this fix in which we need: https://github.com/lbovet/docson/pull/41/files to handle json pointers in external files

There are three things we need to address:

• (1) Decide whether this should be part of the theme instead? (I'm agnostic)
• (2) Make sure our readme guidance and build processes properly initialise the submodule OR move to just using a static rather than sub-module copy
• (3) Make sure we can use a copy with https://github.com/lbovet/docson/pull/41/files fix applied

[odscjames]

(1) Maybe it should probably be part of the the data-standard repository, as in theory someone could take the content and use it with a different theme, and in those cases, docson would be required? (I think) I don't know tho.
(2) The readme for this repo only mentions Vagrant and it's in that ;-) Could be in https://github.com/openownership/data-standard/blob/master/README.md tho.
(3) Ok, I'm going to look at this ...

[timgdavies]

Thanks :) Reasoning for having this in the standard makes sense to me :)

Thanks for looking into (3).

[odscjames]

Ok, so I've made a version of docson with all the latest code, and our 2 small patches on top of it.

To try it, Change to the docson directory and run:

odsc@james-XPS13-9333:~/work/openownership-data-standard-sphinx-theme/data-standard/docs/_static/docson$ git fetch
...
odsc@james-XPS13-9333:~/work/openownership-data-standard-sphinx-theme/data-standard/docs/_static/docson$ git checkout 320619aa1a1a3e9b7b580e88f713c71f3122ce54
Previous HEAD position was 8ea21cd... Edit README.md
HEAD is now at 320619a... Display types and format in docs schema viewer

NOTE; if you commit at this point you'll also commit this update for everyone. You probably don't want to do that! To put this back how it was before, run:

odsc@james-XPS13-9333:~/work/openownership-data-standard-sphinx-theme/data-standard/docs/_static/docson$ git checkout 8ea21cd9c34e7379a2ac0aba640933901345d7d3
Previous HEAD position was 320619a... Display types and format in docs schema viewer
HEAD is now at 8ea21cd... Edit README.md

Anyway, give that a good test, let me know if it solves your problem. (For me I can't compile the site at all at the moment.)

[timgdavies]

Just tested and that commit was working nicely in a fresh rebuild of the docs :)

[odscjames]

Cool - I'm not sure what branch to go for but if you want to commit this on a branch of the data standard, simply run the "git checkout 320619...." command in the "docson" folder and then go up to the "data-standard" folder and git commit as normal. It should show a change in "docs/_static/docson"