Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use native docutils for field lists, notes, and warnings #670

Merged
merged 1 commit into from Apr 2, 2021

Conversation

jakobandersen
Copy link
Collaborator

For parameter lists, template parameter lists, return, throw, pre, and post, use the native field lists in docutils and make sure to collect them into a single field list per declaration to enable the Sphinx post transform that groups fields and makes cross-references (DocFieldTransformer).
For warnings and notes, also use the native nodes as if the directives warning and note were used.

Fixes #599.

Example

index.rst:

.. cpp:function:: template<typename T1, typename T2> \
                  void f_raw(int a, float b, std::string c)

	Do stuff.

	More description.

	.. warning:: don't do this
	.. note:: be careful

	:param a: first param
	:param b: second param
	:param c: third param
	:throws: char if something
	:throws: long int if something else
	:tparam T1: first template param
	:tparam T2: second template param
	:pre: stuff must be correct
	:pre: more stuff must be correct
	:post: stuff will be nice
	:post: more stuff will be nice
	:returns: nothing

.. doxygenfunction:: f_doxygen

test.hpp:

/*!

  \brief Do stuff.
  \param a first param
  \param b second param

  More description.

  \param c third param
  \throw char if something
  \throw "long int" if something else
  \tparam T1 first template param
  \tparam T2 second template param
  \pre stuff must be correct
  \pre more stuff must be correct
  \post stuff will be nice
  \post more stuff will be nice
  \return nothing
  \warning don't do this
  \note be careful
*/
template<typename T1, typename T2>
void f_doxygen(int a, float b, std::string c);

Current Breathe rendering:
current
Similar raw manually written Sphinx, and rendering with this PR:
pr

This includes parameter lists, template parameter lists,
and the simplesects return, pre, and post.
Also use the native admonitions for the simplesects warning and note.

Fixes breathe-doc#599
@vermeeren vermeeren self-requested a review April 2, 2021 15:42
@vermeeren vermeeren self-assigned this Apr 2, 2021
@vermeeren vermeeren added code Source code enhancement Improvements, additions (also cosmetics) labels Apr 2, 2021
Copy link
Collaborator

@vermeeren vermeeren left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jakobandersen Pretty substantial rendering improvement I'd say, looks a lot nicer especially with many parameters etc. Thanks again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
code Source code enhancement Improvements, additions (also cosmetics)
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Different parameter/return rendering from official sphinx
3 participants