Inconsistencies in rendering docs vs. Jupyter notebooks (Qiskit Optimization)

[Travis-S-IBM]

This issue points out some places where information (mostly text) is rendered inconsistently between the docs on qiskit.org/documentation and the corresponding Jupyter notebooks which generate the pages.

1 Quadratic Program

• Above cell 13, the list of substitutions gets inlined.

2 Converters for Quadratic Programs

• The list of converters in the opening paragraphs gets inlined.

3 Minimum Eigen Optimizer

• The list of MinimumEigenSolvers in the opening paragraphs gets inlined.
• The hyperlinks for references 1 and 2 are not rendered correctly.

4 Grover Optimizer

• The hyperlink for reference 1 is not rendered correctly.

5 ADMM Optimizer

• The hyperlinks for references 1 and 2 are not rendered correctly.
• The list of solvers just under cell 1 gets inlined.

6 Max-Cut and Traveling Salesman Problem

• The steps listed in the 2nd paragraph of section Approximate Universal Quantum Computing for Optimization Problems are inlined.
• The references above Cell 2 are inlined.

7 Vehicle routing

• The list just above Cell 9 gets inlined.

[Travis-S-IBM]

@nonhermitian Who would be the person to work with to figure out why these inconsistencies happen?

[nonhermitian]

Limitations number four in the readme might help.

[Travis-S-IBM]

@nonhermitian How so? There's no math in these lists....

Is there a doc somewhere that outlines how the rendering as RST files works?

[nonhermitian]

Ok, I guess I misunderstood the issues. Here is a link to the conversion program docs:

https://nbsphinx.readthedocs.io/en/0.7.1/

In short, Sphinx parsing is much more strict than that allowed in Jupyter notebooks. This is why you are seeing what you do.

[mtreinish]

It's worth pointing out the actual rst generation is done using pandoc (at least until spatialaudio/nbsphinx#36 is implemented). Basically nbsphinx runs nbconvert on the notebook to generate a markdown file then runs pandoc on that markdown output to generate restructured text which is what gets passed to sphinx for building the html version. The pandoc conversion is where I expect this is going wrong, there are a lot of edge cases there and pandoc doesn't always know what a renderer is looking for.

[nonhermitian]

Closing as (kind of) solved. Can reopen if otherwise.

[shil-m]

Ok, I guess I misunderstood the issues. Here is a link to the conversion program docs:

https://nbsphinx.readthedocs.io/en/0.7.1/

In short, Sphinx parsing is much more strict than that allowed in Jupyter notebooks. This is why you are seeing what you do.

Has this been fixed? Because the documentation is still inconsistent for 6 Max-Cut and Traveling Salesman Problem