I'm not sure if it is an issue of my local environment, but if I click on the Language Setup > Introduction page, the correct page is open but the left menu highlights the Getting Started with Webots > Introduction to Webots instead of the correct page.

I have this issue only when using the offline dock documentation widget.
I tested on the #102 branch.

We should not use PROTOs in the documentation and in the ChangeLog, instead it would be better to use the single form PROTO followed by a plural name like files or nodes.

For now, the formula sources are still into the TEX format in the webots/src/doc/formulas/ repository.

A better integration seems obviously required.

Several Javascript are doing mathematical text to HTML formula view conversion very well including:

• MathJax
• AsciiMath

MathJax is supposed to support TEX formulas, amongs other, which seems to be the shortest way to import our formulas.

Some code snippet are existing to integrate this into showdown:
https://gist.github.com/xentec/6588519
https://gist.github.com/npisenti/3028983

Instead of creating branches specific to a version as we have done for the fist time for Webots 8.5.3, and let the online documentation point on webots-doc master, it would be certainly easier to put all the modifications in master, and let the online documentation point on the git tag matching with the current Webots version.

In the online documentation, notes have an icon.
For example at the bottom of the Accelerometer page:
https://www.cyberbotics.com/doc/reference/accelerometer

But this icon is not displayed in the offline documentation.

Rename the ms argument to `sampling_rate``, for all the sensors, and to indicate that its unit is in milliseconds in the comments. => The argument name should describe its purpose, not its unit.

We are using the "Mac OS X" keyword everywhere in the doc. Is this good?

Because these final semi-colons are missing, the function on the second line is not properly syntax highlighted on github. See for example: https://github.com/omichel/webots-doc/blob/master/reference/robot.md (scroll down to wb_robot_step() function).

Currently, the Webots version is hardcoded here:

https://github.com/omichel/webots-doc/blob/gh-pages/scripts/showdown-extensions.js#L27

Defining it into a root file (such as "webots_version.txt" or so) would be better (but quite annoying to implement, because the javascript should load this file).
A better solution would be to create a javascript file especially for this.

We could think about adding a test which checks that the version stored in this file is matching with https://www.cyberbotics.com/webots_current_version.txt

Similarly, the date could be generated on the fly.

Would it be complicated to check that the branch (and repo) tag is valid and print a warning if it is not?
Because currently the doc looks empty and buggy when the tag is wrong, see for example this branch who was just deleted a few minutes ago: https://www.cyberbotics.com/doc/automobile/traffic-signs-and-lights?version=enhancement-mac-installation

When you visit https://www.cyberbotics.com/doc/reference/robot and scroll down and then you click on the Camera section, the camera documentation is displayed, but the vertical scrollbar is not reset to the top as the user would expect. That looks wrong.

A client asks for a PDF version of what we can find on the website, in particular the User Guide and the Reference Manual.

We should see if there is an easy way to create a PDF from current HTML version.

It would be nice to be able to click images and have a modal dialog appear to preview the image in its full-size format.

Similarily to #7, the diagram sources are still into the DIA format in the webots/src/doc/dia/ repository.

Here too, a better integration seems to be required.

This issue aims to report the best candidates to do so.

I believe it is better that the main page of the books is renamed to index.md instead of bookname.md, e.g., guide/index.md rather than guide/guide.md.

One can find only documentation about arguments of the streaming feature:

https://www.cyberbotics.com/doc/guide/starting-webots

Creating a section explaining at least:

• purpose of this feature
• where to find the streaming viewer page
• what can be streamed
• what are the limitations
• Links from starting-webots to this section, and vice versa.

Both the online and offline versions of the doc are affected by this problem, but not the same way...

We should describe how to use an alternative Python (make -C resource/languages/python) in order to support other Python environments (such as the homebrew one)

Slightly related with https://github.com/omichel/webots/pull/4665

The code should be highlighted when the markdown tags are referring to some language:

https://github.com/omichel/webots-doc/blob/master/guide/tutorial-4-more-about-controllers-20-minutes.md#program-a-controller
https://www.cyberbotics.com/doc/guide/tutorial-4-more-about-controllers-20-minutes#program-a-controller

This is working locally, but not on the Cyberbotics website.

Maybe it's due to #90!?

If you go to this page: https://www.cyberbotics.com/doc/reference/accelerometer and click on one of the Accelerometer links, it work fine (position modified and url changed to https://www.cyberbotics.com/doc/reference/accelerometer#accelerometer) but then if you press again on a Accelerometer links it doesn't do anything.

Note that I was able to reproduce this on Firefox (Linux) but on Chrome everything is working fine.

Using the class HTML attribute in the documentation will help us avoiding conflicts with the CSS of Cyberbotics' web site. The name of the class could be webots-doc. We should split the current main.css file into two files: main.css would remain the main CSS file of Cyberbotics' web site whereas webots-doc.css would contain only the class specific CSS for the Webots documentation. Only the webots-doc.css stylesheet file should be distributed with Webots.

This image is bad as it contains a white contour that should be removed: https://github.com/omichel/webots-doc/blob/master/robotis-op2/images/titleweb.png

Moreover, the title of the image should be changed to robotis-op2.png

When adding a new section, it's easy to forget to add its reference in the corresponding chapter, as there:
https://github.com/omichel/webots-doc/blob/master/reference/nodes-and-api-functions.md

Adding tests for this based on the menu.md file would be useful to not forget this.

This URL doesn't scroll down to the wb_robot_get_device section, as it should:
https://www.cyberbotics.com/doc/reference/robot?version=fix-robot-doc#wb_robot_get_device

From @fabienrohrer on January 19, 2016 8:36

Units and range in documentation are heterogenous, and sometimes missing.

Related forum messages:
https://www.cyberbotics.com/forum?message=5836
https://www.cyberbotics.com/forum?message=1339
https://www.cyberbotics.com/forum?message=2361

Copied from original issue: omichel/webots#3414

Our note and code sections are not very well looking. In particular, the note sections have a too big font size and the code sections have a too small font size... See for example https://www.cyberbotics.com/doc/reference/camera

A nice looking example of note and code sections can be found here:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Introduction_to_Object-Oriented_JavaScript

Likewise, we could use some icons, colors or background images to improve the appearance of these sections. However, it seems this mozilla layout doesn't allow code inside notes which we do allow.

The screenshot main_window.png still shows the version Webots 7.3.0.

I don't think it is necessary to update the screenshots every minor version, but it would be better to do it every major version change.

Now that have a nice online viewer allowing us to visualize easily any branch, I believe there is no need to maintain this gh-page branch as the default branch. We should use the master branch instead.

I noticed that most of the code snippets uses the following form without checking for the wb_robot_step return value:

while(1) {
  ..
  wb_robot_step(TIME_STEP);
  ..
}

An the wb_robot_cleanup is not used, at least in the Controller Programming section.

Wouldn't be better to improve the examples in order to show to the users the correct way to implement their controller?

https://github.com/omichel/webots-doc/wiki

For now, I put the most basic information about this repo, but it could be improved in proper time.

As discussed in #80, the field description is much more readable if an empty new line is inserted between the list items.
At the moment the source files are not consistent and some of them uses these empty lines and some not.
So it would be better to check and add the new line in all the nodes' fields description listing the fields in bullet format.

For information, the clang static analyse gave these issues:

Dead store: Dead assignment: Value stored to 'det' is never read
1: Value stored to 'det' is never read in /home/daniel/develop/webots/projects/robots/robotis-op2/libraries/robotis-op2/robotis/Framework/src/math/Matrix.cpp:100

Memory Error: Memory leak: Potential leak of memory pointed to by 'protoList'
1: Assuming 'isValidProject' is 0 in /home/daniel/develop/webots/src/webots/app/WbApplication.cpp:266
2: Memory is allocated in /home/daniel/develop/webots/src/webots/app/WbApplication.cpp:266

Dead store: Dead assignment: Value stored to 'found' is never read
1: Value stored to 'found' is never read in /home/daniel/develop/webots/src/webots/core/WbMacAddress.cpp:121

Logic error: Division by zero
1: Loop body executed 0 times in /home/daniel/develop/webots/src/webots/maths/WbMathsUtilities.cpp:274
2: Division by zero in /home/daniel/develop/webots/src/webots/maths/WbMathsUtilities.cpp:303

Dead store: Dead assignment: Value stored to 'max' is never read
1: Value stored to 'max' is never read in /home/daniel/develop/webots/src/webots/nodes/WbColor.cpp:45

Logic error: Called C++ object pointer is null
1: Calling 'computePath' in /home/daniel/develop/webots/src/webots/nodes/utils/WbUrl.cpp:96
2: Passing value via 1st parameter 'node' in /home/daniel/develop/webots/src/webots/nodes/utils/WbUrl.cpp:25
3: Calling 'computePath' in /home/daniel/develop/webots/src/webots/nodes/utils/WbUrl.cpp:25
4: Assuming pointer value is null in /home/daniel/develop/webots/src/webots/nodes/utils/WbUrl.cpp:58
5: Loop body executed 0 times in /home/daniel/develop/webots/src/webots/nodes/utils/WbUrl.cpp:58
6: Loop body executed 0 times in /home/daniel/develop/webots/src/webots/nodes/utils/WbUrl.cpp:72
7: Called C++ object pointer is null in /home/daniel/develop/webots/src/webots/nodes/utils/WbUrl.cpp:78

Logic error: Called C++ object pointer is null
1: Value assigned to field 'mField' in /home/daniel/develop/webots/src/webots/scene_tree/WbFieldEditor.cpp:198
2: Assuming pointer value is null in /home/daniel/develop/webots/src/webots/scene_tree/WbFieldEditor.cpp:209
3: Calling 'WbFieldEditor::computeFieldInformation' in /home/daniel/develop/webots/src/webots/scene_tree/WbFieldEditor.cpp:214
4: Called C++ object pointer is null in /home/daniel/develop/webots/src/webots/scene_tree/WbFieldEditor.cpp:276

Then if the left menu area is small the section titles are not included in the menu gray area (see BallJointParameter section title in the following screenshot):

Additionally if the documentation widget width is small the up, left and right arrow icons overlap.

The position of the horizontal scrollbar is a little bit weird if the page content is short.
I would probably expect it to be in any case at the bottom of the widget instead of at the end of the page content:

It would be nice to be able to visualize branches from forked repositories (as users will have to fork the repository to contribute and will want to see the result before raising the thumb up on the pull request).

It should be possible to create hyperlinks across books using relative pathes (e.g. from the guide use [Camera](../reference/camera.md)). Unfortunately it seems to work on Github but not in our viewer (on Cyberboitics website).

Once fixed, the references in the description of radarCrossSection and recognitionColors in automobile/ackermannvehicle.md` should be added.

The spacing is not consistent between the data type and the field name and between the field name and the default value and between the default value and the comment. Sometimes, we have a minimum amount of spaces (up to 1) and sometimes, we have an arbitrary number of spaces, like here 4 or 5.

When clicking on an external URL in the offline Webots documentation nothing happens.
I have this issues at least on Linux.

For example:
User Guide -> Language Setup -> Using ROS -> "Willow Garage" link at the end of the first paragraph.
https://github.com/omichel/webots-doc/blob/master/guide/using-ros.md#what-is-ros

On the cyberbotics website and on GitHub it works correctly.

Add documentation of IndexedFaceSet.ccw field.

In the User Guide we use the Note: format but in the other books (Reference Manual, automobile and darwin-op) we use note:.

Personally, I don't have any preference on the format but it would be good to use the same format in all the books.

It is not documented how to launch the SUMO tools included in Webots from a terminal (the modification of the PATH or so, and the location of these binaries).

The 'Show Robot Window' in the 'Robot' menu is not documented:
https://www.cyberbotics.com/doc/guide/the-user-interface#view-menu

From @omichel on October 21, 2015 14:43

In the user guide and reference manual, we should take care of the image sizes so that they display nicely on our web site without oversize problems like this: http://www.cyberbotics.com/guide/section2.3.php

It should be obvious to fix by adding an appropriate value to the scale field to the graphic node in the XML doc files.

Copied from original issue: omichel/webots#3123

It seems that the upper case NVIDIA version is the preferred spelling.
We should check that we always use the same upper case format in everywhere in the documentation.

It is planned to integrate the new documentation to the Cyberbotics website for Webots 8.5.0.

To do this, it seems that the best way is to redirect the cyberbotics/guide to github.io/?index.html?book=guide and so on.

The redirection may be more or less complex depending on what we would like (GET attribute forging, etc.)

On this page: https://www.cyberbotics.com/doc/reference/robot#wb_robot_get_device
The See also → section looks bad. Instead of section, we should display wb_robot_step.

At the moment the HTML robot windows functions are not documented.
I don't know in which version we want to make them public but it is good to have an issue in order to not forget it.

From @Cypherluc on November 26, 2013 10:25

In the reference manual, it would be nice to have schemas such as the one in the InsertNodeDialog depicting the joints visually.

Copied from original issue: omichel/webots#84

The develop branch has been created, the usual workflow can be applied.

The develop branch doesn't differ from the master branch for now.

Upon changing or clicking on a new section in here, the ID tag (i.e. remidhum) disappears. This causes some pages not to load up (Advertising Board in particular) and if refreshed, none of the pages load.
However, as long as the page is not refreshed, the rest of the sections will correctly open even without the name tag.

After a refresh (and a sub section change), the url is similar to this:

https://www.cyberbotics.com/doc/automobile/buildings?version=doc-automobile-objects

By adding remidhum: just after version= fixes the problem.

https://www.cyberbotics.com/doc/automobile/buildings?version=remidhum:doc-automobile-objects

From @DavidMansolino on January 27, 2016 8:49

The user guide Sample Webots Applications (http://www.cyberbotics.com/guide/sample-webots-applications.php) chapter is largely outdated, a large number of samples are not included. Maybe once the new documentation system will be working it will be good to refactore it (add missing samples, replace pictures by x3d models /animations, etc.).

Samples (should be renamed Demos):

• missing anaglyph
• missing uneven_terrain
• order should be checked (should be order alphabetically to match order in the 'Open Sample World' window)

Devices:

• missing camera_auto_focus
• missing camera_compositors
• missing camera_noise_mask
• missing display
• missing force3d_sensor
• missing gyro
• missing hokuyo
• missing inertial_unit
• missing laser_pointer
• missing lidar
• missing position_sensor
• missing propeller
• missing receiver_noise
• missing sick
• missing spherical_camera
• missing supervisor
• missing track

Howto:

• missing asymmetric_friction1
• missing asymmetric_friction2
• missing center_of_mass
• missing contact_points
• missing cylinder_stack
• missing four_wheels
• missing gui_tracker
• missing omni_wheels
• missing passive_dynamic_walker
• missing pedal racer
• missing rope
• missing sick_terrain_scanning
• supervisor should be renamed soccer_demo
• missing vision
• missing ziegler_nichols

Geometries:

• missing capsule
• missing extended_solids
• missing extrusion
• missing floating_geometries
• missing high_resolution_indexedfaceset
• missing textured_boxes
• missing textured_proto_shapes

Missing environments category:

• indoor/apartment
• indoor/kitchen
• indoor/spinning_top (is this really the right location for this sample?)

The mybot directory is missing and seems redundant with the devices category.

The Real Robots part should be updated and is somehow redundant with the Robots chapter (http://www.cyberbotics.com/guide/robots.php).

Copied from original issue: omichel/webots#3437