-
Notifications
You must be signed in to change notification settings - Fork 66
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Feature: needimport supports caching and configured needs.json sources #1148
Comments
We have done already some analysis and tests in the past but Sphinx is a beast and has always overwritten or not accepted our changed links. So further work is needed here. I guess this ticket is a duplicate of #689. |
@danwos: Thanks for your quick answer. I already assumed that it would not be easy to do. Also, needextract can appear multiple times for the same need... in this case, it's probably hard to do proper error handling. I've therefore adapted the issue to consider a new solution approach, improving the featur set of needimport. |
Here is a technical proposal for the problem.
IdeaProvide a "importable_objects" database/dict, which holds all importable need-objects and is loaded/filled only once, at the beginning of a sphinx-build. This is technically related to the SpecProvide a new needs_importable_data = {
"my_data": {
"url": "http://example.com/docs/needs.json" # or use "path"
"path: "my/docs/needs.json" # relative to conf.py
"version": "1.0"
"filter": "status == 'open'"
}
}
The .. needimport:: my_data The data is separated by the key of
|
Hi @danwos , I like the proposal. Please make "path" accept both absolute and relative paths. Just one open point:
Does this restriction also exist for needimport? Do you mean that the data is not available without a needimport that actually imports it? Or in general not? |
Correct, the data is not available as long as it got not imported via |
I don't feel (yet) another configuration option is needed, just add an (optional) key to |
@chrisjsewell : The way of importing is conceptually different.
This means, needimport and the associated new option (name tbd), is closer to our custom extensions that provide directives to create (import) needs loaded from some files, than it is to needs_external_needs. |
I'm afraid I disagree; there should be one clear way for users to define external need data sources, it does not need to be any more confusing Both
no this is not the case; you simply need a source of needs data items, which can be anything that adheres to the needs data schema |
@chrisjsewell : I have given you my perspective as a user of sphinx-needs. With needimport, I'm placing needs in my project, i.e. they appear as original "document nodes". with needs_external_needs, I'm only referencing them and their "document node" appears in another project. I support the wish to keep sphinx-needs configuration options to the minimum number required, but in this case at least I as a user would be confused. @danwos : In the end it's your call as a product owner. Now you've heard two perspectives, my user experience as a needs-import/needs_external_needs power user, and @chrisjsewell's perspective with the developer PoV. |
yeh no worries, its good to discuss 👍 and I see your viewpoint as well |
We've used needextract to show a few needs out of many, many needs imported from some other tool (via needs.json and needimport) in the right place in the documentation.
What bugs me is that the links never go to the place where the needextract is rendered, but always to the location where the original need is defined. This is a problem for the actual use case needextract was made for: If I want to generate a customer documentation (in HTML!) and want to show only the relevant parts of needs to the customer, I would do something like this:
And in the actual docu:
What I get with this approach is an error message / extension error at the end of the build process:
Alternatives considered
An alternative would be to "needimport" the same needs.json many times. But I fear that this would not be so performant for my use case (7000 needs). Maybe, if needimport would cache all need and not re-read the same json file twice, this might not be a big build time problem, but I also don't want to have people provide the same needs.json path in 1000 individual documents.
Also, one needs to be super careful with the filters to avoid importing the same needs twice, while at the same time not forgetting to import those needs which are linked but have no dedicated documentation page.
Expectations
In order to not break the current behavior, maybe add an option to set whether a needextract "overrules" the location of the original link.
Also, add a user friendly error message instead of the extension error above.
Needextract "overruling" locations of original definition may bring it's own bunch of non-determinism problems. Unfortunately, attempts to implement it have also not been successful so far (see #689 ).
So let's rephrase the expectations more generally:
I want a directive to include selected imported needs exactly where I need them, with links going to this page. I want to define the path to the data source (needs.json) only once. I want the data source to be read only once.
Solution idea
I have a suggestion to improve the yaaa-needimport:
The text was updated successfully, but these errors were encountered: