Need more stable URL to reference need elements in HTML

[twodrops]

Sphinx-Needs uses the standard HTML URLs of Sphinx-generated HTMLs to refer to elements with IDs
For example, https://server/sphinx-needs-example-folder/sw_requirements.html#REQ_SwCps_Requirement1

If the folders/files are moved, then the reference to the elements are broken.

It would be nice to have another way to uniquely reference elements with just ID
For example, https://server/needs?query=REQ_SwCps_Requirement1

[danwos]

I like the idea, but I don't think that this is easily possible for a static website.

In my understanding such a query would need some logic to be executed.
This needs to be server-side or in the frontend by some Javascript.

Maybe js-code in the frontend may work, if it has access to a data-file (needs.json?), which contains the current mapping between need-id and url.

This sound a little bit like a feature for a standalone viewer / js-frontend for sphinx-needs.

I will discuss it with some frontend experts to get some ideas for a concept.

[twodrops]

Thanks @danwos. Maybe a local js solution is the easiest and would be inline with the sphinx search feature, which works wonderfully well as a local search.

[arwedus]

@danwos can you narrow down a date for this feature? We have several use cases for it, would be cool to get this in the next few months.

[danwos]

Next few months is possible ;)

The sponsored development (by Prototype Fund) of Open-Needs starts on March and there we need a react based JS Frontend, which will have such a Feature.
As the Open-Needs Server will not be directly available, I think we can use a generated needs.json.
And maybe have something at mid/end of April (if develpmend is done in this context only.)

But maybe we can speed things up, by discussing it with @twodrops internally.

[r-o-b-e-r-t-o]

Hi Daniel, do you have an update on this issue?

[twodrops]

@r-o-b-e-r-t-o We are thinking of creating a reactjs-based interface parallel to a sphinx-theme. This means, instead of static HTMLs, the HTMLs will be rendered dynamically using javascript. It goes in the direction of this idea. This does not replace HTML based theme approach, but is more suitable for usecases which expect dynamic rendering like better responsive UI, filtering etc. The above issue matchings the reactjs approach better as there has to be a javascript based backend which translates the queries. AFAIF, @danwos wanted to start with a protoype of this together with his colleague.

@danwos

[r-o-b-e-r-t-o]

@twodrops @danwos Thanks for the update. This seems to be a big feature. May it be possible to do the backend part first and afterwards the UI stuff? This way we could already use permalinks, which we urgently need for get our bi-directional traceability across tools working.

[twodrops]

@r-o-b-e-r-t-o Yes, I guess it should be possible to start with this feature in the existing setup as well and port it to reactjs theme later. @danwos What do you think?

[danwos]

I agree and I also have thought about it in the last days.

So here is my

technical concept

An additional page permalink.html is added to the project-html build.
This side contains JS code, which loads a needs.json from a configured location.

Redirects to a given Need-ID happen by urls like http://my_docs.com/permalink.html?id=ABC_123.
Then the js-code looks for it in the given needs.json and calculates the path based in the stored docname attribute of the related need.
Finally a simple redirect gets executed.

A new feature/function for layouts is added to add a permalink-icon to each need.
(This link is permanent as long as the ID does not change!).

This feature must be added to the needs_layout by hand for each project.
It is not viewable by default!

The permalink.html gets always added. So this feature is always available.

New config parameters with default
needs_permalink_file = "permalink.html" (must be on root level)
needs_permalink_data = "needs.json" (relative to web-root)

Open questions
Is there a use case, where we need a redirect to another documentation project on a different domain?
So e.g. the external_needs feature is used and on project A an IDs given to project_a/permalink.html for a need from project B.

[arwedus]

That setup matches my idea, cool.
Currently we don't need permalinks over project boundaries

[r-o-b-e-r-t-o]

@danwos Sound like a pragmatic solution. Thanks for sharing this idea. Can you tell when this feature will arrive?

[danwos]

@r-o-b-e-r-t-o is already on it. Let me know if any help is needed.