Some links in documentation are broken

[ShuffleWire]

Describe the Bug
Some reference have the same name, hence clinking on them send to the bad position.

Steps to Reproduce

1. Go to https://www.cyberbotics.com/doc/reference/motor
2. Scroll down to 'get the motor force or torque currently used by a motor'
3. Click on the 'description' link just above
4. It bring you to the top of the page, aka the "Description" of the motor, because you have two identical link https://www.cyberbotics.com/doc/reference/motor#description

Expected behavior
Should bring to the correct location in the page, maybe by having different link (with an auto generated id in the end ?)

[omichel]

Yes, this is a limitation of the current documentation system. If some section or subsection have the same title, the same anchor is generated and the navigator will reach the first one only.

[ShuffleWire]

Would it make sense to try appending an id (only where the conflict is detected ?) ?
it could be like the position in the hierarchy of section/subsection (like https://www.cyberbotics.com/doc/reference/motor#description-2-1 for a description in the 2nd section, first subsection)

[omichel]

Yes, this is a good idea.

[ShuffleWire]

are there scripts that generate documentation ? i don't know where to look

[omichel]

Yes, the documentation is generated on the fly from the MD files by some JavaScript code.

• Example of a MD file
• JavaScript formatting MD to HTML and forging the anchors
• HTML Result

You can modify the JavaScript file to try to fix the problem.
Then, you should create a branch (e.g., my_branch) on this repository from which you will be able to test your change with the following url:

https://www.cyberbotics.com/doc/reference/motor?version=my_branch

Or if the branch lies on your own webots repository:

https://www.cyberbotics.com/doc/reference/motor?version=ShuffleWire:my_branch

[ShuffleWire]

Ok, thank for the indication ! I will have a look, however, I have very little experience with JS, so that could be tricky, but also very interesting.
I will get up updated on any progress.

[ShuffleWire]

How do I test JS script ? should I push to the server and open the html each time, or are there offline option (in-browser debugger etc ?) ?

[ShuffleWire]

I do guess that forgeUrl() is the place to look for changes, correct ?

[omichel]

There is no offline option although it might be possible to craft one. You should actually push your changes on github and see the result from the URL I explained.
Note: sometimes, it seems the result is cached somewhere and you cannot see the result of you last commit, to workaround this, you can also put the commit in the URL, e.g. for commit 2a3f8c3, the URL is:

https://www.cyberbotics.com/doc/reference/motor?version=2a3f8c3

[ShuffleWire]

Just out of curiosity, and to help me get a feet into the code, why do we generate the html on the fly rather that having it built statically ? (regenerated each time a modification is made on md file (in the CI-pipeline), and store on the server the html file) Is it to save space on the server / reduce data transfert to the client / improve flexibility / anything else?

And as I understand, the JS is executed on the client browser, not on the server, correct ?

[omichel]

That just more convenient to manage different versions and have a one-to-one mapping with GitHub.

And as I understand, the JS is executed on the client browser, not on the server, correct ?

Yes.