Skip to content

Commit

Permalink
revert :: => __ rather than single, docs: internal links
Browse files Browse the repository at this point in the history
  • Loading branch information
@svenevs
svenevs committed Jul 31, 2018
1 parent 89904e1 commit f93135f
Show file tree
Hide file tree
Showing 3 changed files with 207 additions and 102 deletions.
4 changes: 1 addition & 3 deletions docs/faq.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -162,9 +162,7 @@ Yes and no. Partial and full template specialization are supported, but not ele
**Full Specialization** ``template <> DerivedClass<bool, 2>``
Produces ``template <> template<> DerivedClass<bool, 2>``

4. See the :ref:`usage_external_linkage_templates`.

5. Where metaprogramming is concerned, it is more likely that Doxygen's preprocessor
4. Where metaprogramming is concerned, it is more likely that Doxygen's preprocessor
needs to have everything ``PREDEFINED``. YMMV.

.. tip::
Expand Down
303 changes: 205 additions & 98 deletions docs/usage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,146 +48,253 @@ Clickable Hierarchies
Linking to a Generated File
****************************************************************************************

.. tip::
Using the linking strategies in this section is primarily for in your website's
documentation such as ``index.rst`` or ``usage.rst`` (since those are already
reStructuredText documents), or even in the supplemental arguments you supply to
``exhale_args`` such as :data:`~exhale.configs.afterTitleDescription` (since these
arguments get "pasted" directly onto a generated reStructuredText document).

This section describes writing links on the reStructuredText side of your
documentation, e.g. inside of the value you provided in
:data:`~exhale.configs.afterTitleDescription` or on your ``index.rst`` or something.
In the actual code documentation, Breathe is typically able to infer links automatically
(which is really great!), as well as you can also use ``\ref`` from Doxygen if that is
not working.

In the actual code documentation, Breathe is typically able to infer links
automatically (which is really great!), as well as you can also use ``\ref`` from
Doxygen if that is not working. See the :ref:`doxygen_documentaion_specifics`
section for in-code documentation linkage.
**Where possible, you should prefer using the Doxygen** ``\ref`` **command**.

You can use the linking strategies in this section, but they are not nearly as
convenient.
However, you can also use these in your code documentation **provided** that you enter a
verbatim reStructuredText. See the :ref:`Doxygen ALIASES <doxygen_aliases>` section for
more information on that.

Assuming you have set ``primary_domain = 'cpp'`` (as shown in the
:ref:`usage_quickstart_guide`), you have two ways to link to documentation being
generated by Exhale. You may want to do this to call attention to key classes or
functions that users should be aware of.
.. _usage_suggested_linking_strategy:

**Suggested Linking Strategy**
By specifying the ``primary_domain``, you should be able to use the linking
strategies `provided by Sphinx itself`__ *without* needing to prefix everything with
``cpp:``. Some examples:
Suggested reStructuredText Linking Strategy
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

+--------------------------------+-------------------------------------------------+
| Action | Syntax |
+================================+=================================================+
| Linking to a class | ``:class:`namespace::ClassName``` |
+--------------------------------+-------------------------------------------------+
| Linking to a method of a class | ``:function:`namespace::ClassName::methodName```|
+--------------------------------+-------------------------------------------------+
| Linking to a function | ``:function:`void namespace::funcName``` |
+--------------------------------+-------------------------------------------------+
Assuming you have set ``primary_domain = 'cpp'`` (as shown in the
:ref:`usage_quickstart_guide`), you should be able to use the linking strategies
`provided by Sphinx itself`__ *without* needing to prefix everything with ``cpp:``.
Some examples:

__ http://www.sphinx-doc.org/en/stable/domains.html#id2
__ http://www.sphinx-doc.org/en/stable/domains.html#id2

**Using Exhale's Internal Links**
If the above are not working, you can try using the links that Exhale generates to
perform its own internal linkage. These links are much harder to use directly.
+--------------------------------+-----------------------------------------------------+
| Action | Syntax |
+================================+=====================================================+
| Linking to a class | ``:class:`namespace::ClassName``` |
+--------------------------------+-----------------------------------------------------+
| Linking to a method of a class | ``:func:`namespace::ClassName::methodName``` |
+--------------------------------+-----------------------------------------------------+
| Linking to a member of a class | ``:member:`namespace::ClassName::mMemberName``` |
+--------------------------------+-----------------------------------------------------+
| Linking to a function | ``:func:`namespace::funcName``` |
+--------------------------------+-----------------------------------------------------+

.. tip::

You would use these links if you need to link to something that the Sphinx domain
does not have available, e.g. a File page being generated.
.. tip::

As the generation of these links becomes a little entrenched (it takes place in the
function :func:`~exhale.graph.ExhaleRoot.initializeNodeFilenameAndLink`) I advise you
to simply generate the API once with ``make html``, and look at the **top** of the
reStructuredText document. For example, if you wanted to link to the file
``directory/common.hpp``, the link at the top of the file will usually be
The value of ``primary_domain`` in ``conf.py`` is **very** important here! If you do
not set it, the default is ``py`` (python). This means that instead of
``:class:`namespace::ClassName``` you would need to use
``:cpp:class:`namespace::ClassName``` to use a different *domain*.

.. code-block:: rst
A much more thorough walk-through of how the different domains can be used together
(e.g., how to link to a ``define`` or macro) is provided in the companion website's
`Using Intersphinx`__ guide.

.. _file_directory_common.hpp:
__ http://my-favorite-documentation-test.readthedocs.io/en/latest/using_intersphinx.html

Meaning in your reStructuredText you would write
``:ref:`file_directory_common.hpp```.

.. _usage_external_linkage_templates:
.. _using_exhale_internal_links:

Linking to a Generated Template
Using Exhale's Internal Links
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. tip::
If the above are not working, you can try using the links that Exhale generates to
perform its own internal linkage. These links are much harder to use directly.
**However, there are some documented compounds that can only be linked to using these
internal links.** These are either because Exhale does not use the corresponding
Breathe directive (e.g., ``namespace``) **or** there does not exist an equivalent link
type in the Sphinx C++ domain (``file`` and ``dir``).

See the three ``DerivedClass`` examples on the `ExhaleCompanion File Page <ecfp_>`_
that defines these examples.
.. _usage_linking_to_the_root_api_document:

.. _ecfp: http://my-favorite-documentation-test.readthedocs.io/en/latest/api/file_arbitrary_DerivedClass.h.html#classes
Linking to the Root API Document
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
.. todo::

**All** templates produce build warnings, but should still give "usable" output.
See the FAQ entry on :ref:`faq_metaprogramming_and_template_specialization`
In Exhale v1.0.0 (when full-fledged projects are supported) each heading on
this page will receive a formal reStructuredText label to ease the process
of linking to this page.

The links generated for templates are particularly obtuse. Consider the following
definitions (implementation redacted):
.. danger::

.. code-block:: cpp
This has an important consequence for **you**! If you use the linking strategy
described here, when formal reStructuredText labels are introduced, your links
will likely break (because it changes the anchor point from the title to the
generated label).

namespace arbitrary {
// the unspecialized template class
template <typename T, unsigned int N>
DerivedClass : BaseClass { /* ... */ };
The link generated is entirely defined by what you specify to ``exhale_args`` with the
keys :data:`~exhale.configs.rootFileTitle`, :data:`~exhale.configs.rootFileName` and
:data:`~exhale.configs.containmentFolder`. Consider the values

// a partial specialization; `struct arbitrary_struct` defined elsewhere
template <unsigned int N>
class DerivedClass<arbitrary_struct, N> : BaseClass { /* ... */ };
.. code-block:: py
// a full specialization
template <>
class DerivedClass<bool, 2> : arbitrary::BaseClass { /* ... */ };
exhale_args = {
"containmentFolder": "./api",
"rootFileName": "library_root.rst",
"rootFileTitle": "Library API"
# ... other arguments ...
}
Keeping in mind that template classes with the same name but different template
parameters are not allowed, e.g.:
Exhale will generate the file ``{containmentFolder}/{rootFileName}`` (so
``./api/library_root.rst``) with an H1 heading ``{rootFileTitle}`` like so:

.. code-block:: rst
Library API
===========
Other stuff generated by Exhale...
To link to the top of this generated document, you can use a reStructuredText link such
as

.. code-block:: rst
.. html, not rst! ----------vv
.. vvvv
Please see the `full Library API <api/library_root.html#library-api>`_
.. |--------------| |-------------------| |---------| |
.. 1 2 3 4
1. The hyperlink text generated will be what is **before** the ``<target>``. In this
example the hyperlink text will be ``full Library API``.
2. Inside of the ``<angle brackets>`` is the actual hyperlink target. Note that this is
a relative path here, so the above link would work for ``index.rst``, but would not
work for say ``tutorials/getting_started.rst``.
3. Lastly, the anchor point is derived from what you specified as the root file title.
The general scheme for how reStructuredText generates these links is basically
``target.lower().replace(" ", "-")``, but special symbols are treated differently.
4. The trailing ``_`` after ``#library-api>`` is **required**! That's how
reStructuredText hyperlinks work.

.. _usage_linking_to_special_cases:

Linking to "Special Cases": namespaces, files, and directories
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The work for generating these links takes place in
:func:`ExhaleRoot.initializeNodeFilenameAndLink <exhale.graph.ExhaleRoot.initializeNodeFilenameAndLink>`.
The relevant section of the code:

.. code-block:: py
SPECIAL_CASES = ["dir", "file", "namespace"]
if node.kind in SPECIAL_CASES:
if node.kind == "file":
unique_id = node.location
else:
unique_id = node.name
unique_id = unique_id.replace(":", "_").replace(os.sep, "_").replace(" ", "_")
# ... later on ...
if node.kind in SPECIAL_CASES:
node.link_name = "{kind}_{id}".format(kind=node.kind, id=unique_id)
.. code-block:: cpp
Some examples of links you would use:

// definition 1
template <typename T, unsigned int N>
DerivedClass : arbitrary::BaseClass { /* ... */ };
- ``namespace foo::bar::baz``:

// definition 2
template <bool useFloat, unsigned int N>
DerivedClass : arbitrary::BaseClass { /* ... */ };
.. code-block:: rst
The challenge really amounts to how Doxygen is presenting this information, and the fact
that the filenames / reStructuredText links need to be "HTML Safe" (no ``<``, ``>``, or
``,``).
.. node.kind
.. |-------|
:ref:`namespace_foo__bar__baz`
.. || ||
.. Two underscores between namespaces!
.. from: replace(":", "_")
**Unspecialized Templates**
The ``node.name`` has no templates, and the Doxygen XML provides a
``templateparamlist`` which is parsed into ``node.template_params``.
- ``file include/outer_dir/inner/file.hpp``:

**Filename**
``class_arbitrary__DerivedClass.rst``
.. code-block:: rst
**reStructuredText Label**
``.. _template_class_arbitrary__DerivedClass:``.
.. node.kind
.. |--|
:ref:`file_include_outer_dir_inner_file.hpp`
**Partial Specializations**
The ``node.name`` **has** templates, and the remaining unspecialized template
parameters are parsed from the XML into ``node.template_params``.
Note that unlike namespaces, ``replace(os.sep, "_")`` will only result in a single
underscore between directories. Note that spaces are not allowed in the generated
links, so they are also replaced with underscores.

**Filename**
``class_arbitrary__DerivedClassLT__arbitrary__arbitrary_struct_COMMA_N__GT.rst``
- ``dir include/outer_dir/inner``:

**reStructuredText Label**
``.. _template_class_arbitrary__DerivedClassLT__arbitrary__arbitrary_struct_COMMA_N__GT:``
.. code-block:: rst
**Full Specializations**
The ``node.name`` **has** templates, but there is nothing to put into
``node.template_params``.
.. node.kind
.. |-|
:ref:`dir_include_outer_dir_inner`
**Filename**
``class_arbitrary__DerivedClassLT__bool_COMMA_2__GT.rst``
Treatment is identical to files, with the same considerations for path separator
and space replacement.


.. _usage_linking_to_any_other_generated_file:

Linking to Any Other Generated File
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. warning::

Using these links directly may be an exercise in futility. You should be able to use
the links described in :ref:`usage_suggested_linking_strategy`.

The work for generating these links also takes place in
:func:`ExhaleRoot.initializeNodeFilenameAndLink <exhale.graph.ExhaleRoot.initializeNodeFilenameAndLink>`.
The relevant section for these constructs is:

.. code-block:: py
unique_id = node.refid
# ... later on ...
node.link_name = "exhale_{kind}_{id}".format(kind=node.kind, id=unique_id)
This is prefixed with ``exhale_`` because there are potential collisions with using the
Doxygen ``refid`` (Doxygen's internal "unique identifier scheme", which is mostly
equivalent to compiler-like C++ name mangling with some potential hashing and
divergences). The collisions come from the fact that Breathe will typically create an
anchor point that is exactly the Doxygen ``refid``. The Breathe anchors are where the
links such as ``:class:`namespace::ClassName``` **as well as** your standard ``\ref``
calls will direct to. This is ideal.

The Exhale links are anchor points to the top of the generated page that has the Breathe
directive in its body. These anchor points are used for indexing the tree view.

.. tip::

If for whatever reason you want to use the Exhale internal links, you can save
yourself a lot of time trying to figure out what they might be and just generate the
api once. Open up the generated file for the desired node, and look at the top.

.. code-block:: rst
.. _exhale_class_somecrazy_thing:
Class ``somecrazy_thing``
=========================
Copy-paste the thing at the top starting with ``.. _``, noting that in this
particular (hypothetical) example, you would use
``:ref:`exhale_class_somecrazy_thing``` **without** the leading underscore. The
leading ``.. _`` is what tells reStructuredText "I want this to be the name of the
link".

.. note::

**reStructuredText Label**
``.. _template_class_arbitrary__DerivedClassLT__bool_COMMA_2__GT:``
The internal links changed in a breaking way with Exhale v0.2.0. Unless an
exceptionally compelling reason comes up, I hope to never change the internal link
generation again.

.. _usage_customizing_file_pages:

Expand Down
2 changes: 1 addition & 1 deletion exhale/graph.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1984,7 +1984,7 @@ class view hierarchy (<a href="..."> for the ``createTreeView = True`` option).
else:
unique_id = node.name

unique_id = unique_id.replace(":", "_").replace(os.sep, "_").replace(" ", "_").replace("__", "_")
unique_id = unique_id.replace(":", "_").replace(os.sep, "_").replace(" ", "_")
if node.kind == "namespace":
title = node.name.split("::")[-1]
else:
Expand Down

0 comments on commit f93135f

Please sign in to comment.