Make :file: directive option actually optional

[jnikula]

Provide a way to reduce or drop the need to specify the file with :file: for every directive, every time.

From https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/23145#note_1920081 and https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/23145#note_1923559

"Having to state the file every time is a bit annoying but ultimately harmless."

"Would it work to have a declaration thing where you list a bunch of files and then anything from any of those files can be used without an explicit file declaration? Or does it really need to be one file at a time?"

#156 picks up the low-hanging fruit, but it might be better to aim higher from the start.

[jnikula]

Ping @BrunoMSantos

[jnikula]

If source files are specified globally in conf.py, they all need to be parsed up front. All rst documents with autodoc directives would need to depend on all of the source files, because you don't really know where the referenced symbols come from. I don't think it's enough to note the dependency based on where the symbol was found on one run.

[BrunoMSantos]

Nice to see mesa guys reporting their experience with this! I haven't had time to read your RFC yet, so caveat emptor.

Using a directive to select a file makes the documentation directives stateful and dependent on where in the document they appear. So I don't really like that, and unless we can only select a single file, it only reduces the scope of the issues, it doesn't avoid them :/

Performance will indeed take a hit, especially if we want to be accurate (e.g. warning of aliased symbols implies searching all files for each symbol), but I'm not too worried about that honestly, especially if we build a permanent cache on disk. But you haven't touched on the worst bit yet I think.

Currently allow different clang options for different directives, which implies parsing all files for each set of clang options we find (like in #75 actually, though I don't think this issue was discussed then). But that may break things if not all files can compile with a certain set of options, and it's unacceptably expensive to parse a whole project as many times as the user specifies the :clang: option.

From the top of my head, we would need to define clang arguments per file / directory (presumably matching those used to build the actual project) and parse files with them. When directives specify additional arguments though, I frankly see no other way around it as we don't know which file we need to parse. Any simplification would come with an accuracy cost I think, so :clang: should probably be dropped or issue a loud suggestion that the user specifies :file: with it.

I'll think about this more carefully in the weekend.

[BrunoMSantos]

From the top of my head, we would need to define clang arguments per file / directory (presumably matching those used to build the actual project)

Just adding a quick thought on this matter: maybe we can leverage the nowadays ubiquitous compile_commands.json (like clangd consumes) as a way of passing per file compilation options to hawkmoth when needed. There's plenty of ways of getting such a file from basically any build system out there, and it's json.

[jnikula]

Fixed by #171