Adding a section option to the doxygenfile directive

[lshamis]

#318

The PR adds a "sections" option to doxygenfile.
The value is a space-separated list of doxygen kinds.

[lshamis]

@vermeeren can you help me get the documentation test fixed up?

[lshamis]

@vermeeren All tests pass. Ready for review.

Note: The github action seems stuck, but Travis has passed.
https://github.community/t5/GitHub-Actions/Github-action-stuck-at-queue/td-p/38003

[alephzero]

ping @vermeeren

I'd like to use this feature

[vermeeren]

Sorry for the wait. The PR itself is good as far as I can see. Could you rebase so the commit history is clean? After that all is good for merging.

Thanks for the patches!

[alephzero]

@vermeeren I'm still a bit new to submitting github prs, and, I guess, git forks.
I ran the following commands in my fork:

git remote add upstream git@github.com:michaeljones/breathe
git fetch upstream
git rebase upstream/master

but wasn't able to push without -f.

Looking at the final code, I don't think I broke anything, but I'm also not sure if the commit history is what you expect. If it's not what you want, let me know what commands I need to run.

[vermeeren]

@alephzero for this specific case fixup into the initial commit should be good.

If you run git rebase -i upstream/master it should show your unique commits (in this PR) in the editor, together with some basic instructions in the comment provided by git. You would then pick the first commit Adding a section option to the doxygenfile directive and fixup the other commits.

This "merges" the later commits' diff into the initial commit, discarding the later commit's messages and other metadata. The result is that git log should now show a single commit on top of origin/master, which contains the full diff of the current PR. You can verify that with git show. Indeed pushing this way requires -f as it is a history rewrite, doing this for PRs/MRs is ok but for master-ish branches this is usually avoided.

Some refs in case you wish to read more:

• https://git-scm.com/book/en/v2/Git-Branching-Rebasing
• https://git-rebase.io/

[alephzero]

Thanks for the info!
I've been using the "Squash and Merge", to commit PRs in github, which (I think) is similar.
I need to learn more about git :)

[vermeeren]

Thanks for the fixup, I also polished some doc after merging which I did not think about earlier.

On a side note, I currently get this with current master and Sphinx 3.0.1.

It seems there is no difference for me if public-type is there or not, though it could be something with my local environment. Could you check too if possible? I will likely release the next version of Breathe after this is looked at and determined to be fine (or if it is bug and then fixed).

[lshamis]

Thank you for the polish and doc fixes!

I think I may have added stuff to nutshell.h when I was testing locally. The file is pretty sparse. We may need to add something to make it an interesting example.

[vermeeren]

I do see current nutshell.h has some public and private class members, which I do see in class_nutshell.xml when building docs, which then has the <sectiondef kind="public-type">.

Do you remember/have some of the changes you made to nutshell.h during testing? I would think public-type lists public members as-is with the master version, but somehow they don't show up for me.

Also, does Doxygen have some documentation or list about the section types available or should this always be manually checked by looking at the XML output? Edit: or possibly these are not directly from Doxygen? Edit2: I am thinking there needs to be some proper doc describing what values can be used for :sections:.

[vermeeren]

I also did some experimentation with your comment in #318 (comment), though I cannot seem to get :sections: briefdescription enum typedef to work locally with the nutshell example either. This needs some further investigation.

[alephzero]

With the current nutshell.h

Using :sections: briefdescription renders

An overly extended example of how to use breathe.

Using :sections: briefdescription public-type public-func private-attrib innerclass renders

An overly extended example of how to use breathe.

class Nutshell
  #include <nutshell.h>

  Public Types

  enum Tool
    Our tool set.

    The various tools we can opt to use to crack this particular nut

    Values:

    kHammer = 0
      What? It does the job.

    kNutCrackers
      Boring.

    kNinjaThrowingStars
      Stealthy.

  Public Functions

  Nutshell()
    Nutshell constructor.

  ~Nutshell()
    Nutshell destructor.

  void crack(Tool tool)
    Crack that shell with specified tool

    Parameters
      tool: the tool with which to crack the nut

  bool isCracked()
    Return
      Whether or not the nut is cracked

  Private Members

  bool m_isCracked
    Our cracked state.

Removing public-type,
Using :sections: briefdescription public-func private-attrib innerclass renders

An overly extended example of how to use breathe.

class Nutshell
  #include <nutshell.h>

  Public Functions

  Nutshell()
    Nutshell constructor.

  ~Nutshell()
    Nutshell destructor.

  void crack(Tool tool)
    Crack that shell with specified tool

    Parameters
      tool: the tool with which to crack the nut

  bool isCracked()
    Return
      Whether or not the nut is cracked

  Private Members

  bool m_isCracked
    Our cracked state.

[alephzero]

nutshell.h only has one class, so innerclass is required in the :section:. You'll need to add top level enums or typedefs for :sections: briefdescription enum typedef to be meaningful on its own.