Exclude Directories and Files? about exhale HOT 4 CLOSED

I like option 2. I think I speak for other breathe users when I say I don't use any other features in all the tools besides generating nice web docs from my doxygen. A lot of examples and user projects online I've looked at use the bare bones default output breathe/sphinx anyway. There's not many 'robust' layout designers for sphinx and Exhale already brings a lot to the table in this sphere because it creates separate pages.

Being able to customize even the .rts outputs just slightly would make this the Exhale/Breathe/Sphinx/Doxygen stack for documentation imo.

from exhale.

Currently no. You just mean at the dump at the bottom, not the hierarchy part right?

The main hurdle with that is Sphinx will emit warnings for every page not included in a toctree. So even though it's still linked in the hierarchy.....Sphinx doesn't understand this.

Presumably you have a larger code base? If so the number of warnings incurred will equal the number of files + directories :/

I will reresearch if there's a way to suppress these warnings. Sphinx 2.0 may have enabled this? Not sure :/

from exhale.

I do not need it to display Files in the project when I already have a file hierarchy tree. #65 (comment)

I have on paper a writer API for consumers which would allow you to write your own python code as a hook that exhale would use, but quite a lot needs to happen before that can become a reality. I'm currently finishing a thesis from hell...so that has priority unfortunately.

I don't think I can get around the "document not included in any toctree" warning, but I see two options

Option 1

Add a config variable "excludeFromUnabridged": ["file", "dir", ...] (open to different / clearer name choices btw). So list all kinds that you want excluded from the unabridged api.

Instead of putting those in the unabridged_api.rst, I think we can get away with generating an orphan.rst page and put all of the toctree for the file pages exhale generates there. The result being that instead of a warning for every file / directory not included, we should get just one warning about orphan.rst not being included in any toctree.

Option 2

Since files and directories specifically are the problem here, we could change the layout of unabridged api altogether. For things like functions / enums, it is advantageous for them to show up on the library root page. It makes it easy to find things that don't show up in the class hierarchy. But for files and directories specifically, we can add a layer of indirection here. The difference would be currently we have something like this

Functions
=========

...

[begin snip]

Directories
===========

...

Files
=====

...

[end snip]

We can take the [begin snip] up to [end snip] and dump them into a layout.rst document. Then at the bottom of the unabridged api, we can do

Layout
======

.. toctree::
   :max-depth: 1

   layout.rst

It'll give a short listing at the bottom of the unabridged API still, but it will be just two bullet points

Layout

- Directories
- Files

1. No warnings about "document not included in toctree".
2. Much cleaner presentation, I agree that dumping all the directories / files isn't really helpful given the file hierarchy on the same page.

Default title of Layout up for debate (can also add a config option to customize it).

What are people's thoughts? I like (2) better because I'd rather not deliberately introduce warnings, and will be easier to implement (read: I can roll that out quickly). (1) is better left for 1.x with the writer API I think (but again, that's a ways off...).

from exhale.

However we could also just do option 1 for now as a hotfix until option 2 is complete. Then mark option 1 flag as deprecated when it builds.

from exhale.