Comments (11)
Not so sure it is lift_definitions per se.
The error is a reference error.
It rather feels like there is an issue in combination with auto_reference or perhaps auto_target.
The thing is that to have a working reference you need to have a title using lift_title = True
.
There is no way around that.
Could you please try the different combinations?
All options False should work, then set lift_definitions
True and so on.
from sphinx-jsonschema.
Assuming a schema with definitions and directives referencing with json-pointer, and without thoroughly digging into each case below, this is the situation:
- When
auto_xxx=True
ANDlift_references=True
ANDlift_title=FALSE
, everything works fine only (lift_description
is irrelevant). auto_xxx=True
ANDlift_references=True
ANDlift_title=True
, fails with warnings(!) for schemas withtitle
elements, but definitions work fine.- All false, fail with _warnings(!) for schemas with references_again, and definitions expectedly do not work.
- The same failures happen when just
auto_xxx=True
OR justlift_references=True
.
Do that make sense? Or i should do elaborate testing?
from sphinx-jsonschema.
That is kind of what I expected except the second case, I would expect that one to work.
I thought at first it was a simple misunderstanding.
I will create my own test sets and experiment to understand better what is happening.
It will be a couple of days before I can look into it.
from sphinx-jsonschema.
Given this schema:
.. jsonschema::
:lift_title: True
:lift_definitions: False
:auto_target: False
:auto_reference: False
{
"title": "outermost title",
"description": "outermost description",
"type": "object",
"properties": {
"param1": {"$ref": "#/definitions/type1"},
"param2": {"$ref": "#/definitions/type2"}
},
"required": ["param1"],
"definitions": {
"type1": {
"$$target": "#/definitions/type1",
"title": "type1 title",
"description": "type1 description",
"type": "integer",
"minimum": 10,
"maximum": 50
},
"type2": {
"$$target": "#/definitions/type2",
"title": "type2 title",
"description": "type2 description",
"type": "string",
"minLength": 8
}
}
}
Tests and results:
I suppose your issue is with cases 9 and 10. Is that correct?
I would have thought that the combination of auto_target
and auto_reference
would have worked.
From the table it appears that auto_target
makes no difference.
The (surprising) case 4 suggests a temporary solution for you.
case | lift_title | lift_def | auto_tar | auto_ref | comment | make output | page displays |
---|---|---|---|---|---|---|---|
1 | True | False | False | False | the default situation | WARNING: undefined label: #/definitions/type1 (if the link has no caption the label must precede a section header) WARNING: undefined label: #/definitions/type2 (if the link has no caption the label must precede a section header) | single table preceded by title value for param1: #/definitions/type1 value for param2: #/definitions/type2 |
2 | False | False | False | False | same as above | same as above | |
3 | True | True | False | False | no error | three tables each preceded by its title value for param1: proper link to type1 value for param2: proper link to type2 | |
4 | False | True | False | False | Unexpected result | no error | same as above |
5 | True | True | False | False | Removed both $$target entries on all remaining cases |
WARNING: undefined label: #/definitions/type1 (if the link has no caption the label must precede a section header) WARNING: undefined label: #/definitions/type2 (if the link has no caption the label must precede a section header) | three tables each preceded by its title value for param1: #/definitions/type1 value for param2: #/definitions/type2 |
6 | True | True | True | False | as above | as above | |
7 | True | True | False | True | no error | three tables each preceded by its title value for param1: proper link to type1 value for param2: proper link to type2 | |
8 | True | True | True | True | as above | as above | |
9 | False | True | False | True | values look like links but do not function properly | WARNING: Unknown target name: "type1 title". WARNING: Unknown target name: "type2 title". | value for param1: type1 title value for param2: type2 title |
10 | False | True | True | True | as above | as above | as above |
from sphinx-jsonschema.
Thanks.
I thought of trying to fiddle with the "description", but figured it wouldn't make a difference.
Now i can think of an explanation: it needs at least a proper text element for the target anchor to attach to.
from sphinx-jsonschema.
I have found the cause the new introduced option :lift_title:
is causing issues with only :auto_reference:
.
The :auto_reference:
option used titles to create link to that part of the table.
The :auto_reference:
worked without using option :auto_target:
The fix would be to update :auto_reference:
and use the created targets by :auto_target:
if :lift_title: False
from sphinx-jsonschema.
I noticed that while lift_description
workarounds the bug, the following setup does not "lift" the descriptions, and these are also embedded in the tables:
jsonschema_options = {
"lift_title": True,
"lift_description": True,
"lift_definitions": True,
"auto_reference": True,
"auto_target": True,
}
from sphinx-jsonschema.
(ok, my last message meshed it up)
As you can see, my configuration had actually lift_title: True
(despite my claims in my comment) and that is why the bug did not appear.
When i set lift_title: False
(like below), the `WARNING Unknown target name" for all definitions are raised.
jsonschema_options = {
"lift_title": False,
"lift_description": True,
"lift_definitions": True,
"auto_reference": True,
"auto_target": True,
}
And i confirm that if all the rest are true, auto_target: False
does not cause problems.
To be succinct, the workaround no4 does not work when schema reuses definitions.
from sphinx-jsonschema.
To prevent messing it up any further but quickly answer your earlier message
The lift_description
was designed to work only with the combination of a title see also documentation.
Maybe discuss separately if required.
from sphinx-jsonschema.
It's a bit annoying how docutils reports broken links but the WARNING Unknown target name
it's generated if there is a reference created but no target to link to.
Regarding case 4 the schema used has a $$target that's equal to the definition if :auto_reference: False
it uses the old method that's why it works.
from sphinx-jsonschema.
case 4: except that lift_title was False. That was the surprising bit for me.
from sphinx-jsonschema.
Related Issues (20)
- sphinx-jsonschema (un)safe for parallel processing? HOT 3
- Schema doesn't get built unless there is something after it HOT 9
- pdb.set_trace() in dependencies code HOT 1
- Configurable `definitions` key HOT 2
- 1.17.0 fails with `KeyError: 'hide_key'`
- Is it possible to have a table of contents and a separate page for each object? HOT 3
- Is it possible to include a copy of the schema json file along with the generated docs? HOT 4
- Confused about how properly use this to automatically generate TOC items from subschemas HOT 1
- Invalid pattern escaping HOT 1
- How to handle schema defined in Python code HOT 8
- How to automatically include all schemas in the source folder HOT 3
- 1.17.2: pytest is failing HOT 2
- Underscores escaped in examples output HOT 14
- 1.19 regression with relative paths HOT 3
- Table doesn't state which attributes are required or not HOT 4
- How to use sphinx directives and multi-line strings in property descriptions HOT 3
- The prefixItems in the array are ignored HOT 2
- module not found HOT 2
- Proper text wrapping of long descriptions HOT 4
- > is swallowed
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from sphinx-jsonschema.