search

xmos / xcore_iot

Other
30 stars 40 forks source link

Lack of URLs to latest XTC tools documentation #434

Closed keithm-xmos closed 2 years ago

keithm-xmos commented 2 years ago

Now that we are adding more HTML documentation to the website, it would be great if we could more easily cross-link between them. Currently, if I want to have some SDK documentation point a user to the documentation for xflash, I need to include a link to a specific version of the XTC Tools documentation.

https://www.xmos.ai/documentation/XM-014363-PC-6/html/tools-guide/tools-ref/cmd-line-tools/xflash-manual/xflash-manual.html

The only link to the latest is a link that takes a user to the top of the documentation - leaving the user to have to spelunk to where xflash is documented.

https://www.xmos.ai/view/Tools-15---Documentation

The URL above will redirect to the latest but URLs to sub-pages will not.

As one can probably imagine, this means we may need to update URLs in the SDK and other HTML documentation every time a new version of a cross-linked HTML page is released. What we desire is the ability to link to a specific version where appropriate or the latest version where appropriate.

keithm-xmos commented 2 years ago

A possible workaround to investigate is the Sphinx extlinks extension.

If the extlink extension works, it is still not ideal as it would require maintaining the base URL to the latests XTC tools documentation inside the SDK.

keithm-xmos commented 2 years ago

A redirect has been added so that you can simply replace XM-014363-PC-6 with XM-014363-PC-LATEST and the website will automatically redirect you to latest available version of documentation for that document partnum.

So now if you go to https://www.xmos.ai/documentation/XM-014363-PC-LATEST/html/tools-guide/tools-ref/cmd-line-tools/xflash-manual/xflash-manual.html

You will be redirected to https://www.xmos.ai/documentation/XM-014363-PC-6/html/tools-guide/tools-ref/cmd-line-tools/xflash-manual/xflash-manual.html

And then when we release the next issue it will redirect you to

https://www.xmos.ai/documentation/XM-014363-PC-7/html/tools-guide/tools-ref/cmd-line-tools/xflash-manual/xflash-manual.html or whatever the latest issue is at the time.