search

Qiskit / qiskit-metapackage

Qiskit is an open-source SDK for working with quantum computers at the level of circuits, algorithms, and application modules.
https://qiskit.org
Apache License 2.0
3.03k stars 749 forks source link

The .. topic:: directive does not get rendered properly #51

Closed pistoia closed 5 years ago

pistoia commented 5 years ago

Based on the template used to render the documentation's RST files in HTML, the .. topic:: directive does not render properly. Consider, for example, the following snippet of RST code:

.. topic:: Extending the Algorithm Library

    Algorithms and many of the components they use have been designed to be
    pluggable. A new algorithm may be developed according to the specific Application Programming
    Interface (API) provided by Aqua, and by simply adding its code to the collection of existing
    algorithms, that new algorithm  will be immediately recognized via dynamic lookup,
    and made available for use within the framework of Aqua.
    Specifically, to develop and deploy any new algorithm, the new algorithm class should derive from
    the ``QuantumAlgorithm`` class.  Along with any supporting  module, for immediate dynamic
    discovery, the new algorithm class can simply be placed in an appropriate folder in the
    ``qiskit_aqua\algorithms`` directory, just like the existing algorithms.  Aqua also allows for
    :ref:`aqua-dynamically-discovered-components`: new components can register themselves
    as Aqua extensions and be dynamically discovered at run time independent of their
    location in the file system.  This is done in order to encourage researchers and
    developers interested in :ref:`aqua-extending` to extend the Aqua framework with their novel
    research contributions.

Using a regular template, this is how the .. topic:: directive above gets rendered:

image

However, using the current template, the .. topic:: directive above does not get rendered in any special way and this is what one gets:

image

Can the current template get augmented to treat the .. topic:: directive as all the other directives? Alternatively, can we use a different template? The Aqua documentation makes extensive use of this directive.

diego-plan9 commented 5 years ago

Actually pinging @Borjagodoy, as it is a theme design issue and better left for a frontend expert! Borja, can you update the CSS so the topic blocks are highlighted in a distinct way? From the docs:

Use the "topic" directive to indicate a self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or transition may occur. Body elements and topics may not contain nested topics.

Ideally we should make those blocks "stand out" according to that semantic meaning.

pistoia commented 5 years ago

@Borjagodoy can you help with this issue? Thank you.

Borjagodoy commented 5 years ago

Yes Today i have any time to fix the differents issues of frontend in the DOC

pistoia commented 5 years ago

Thanks, @Borjagodoy, it looks great.

Borjagodoy commented 5 years ago

The works is of @carlosazaustre :) he is the new Frontend expert for the Doc, good job!!!