search

openownership / data-standard-sphinx-theme

Documentation theme for the Beneficial Ownership Data Standard.
BSD 3-Clause "New" or "Revised" License
0 stars 0 forks source link

Docson dependency & reference resolution #36

Open timgdavies opened 6 years ago

timgdavies commented 6 years ago

(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:

odscjames commented 6 years ago

(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 commented 6 years ago

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

Thanks for looking into (3).

odscjames commented 6 years ago

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 commented 6 years ago

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

odscjames commented 6 years ago

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"