Option to write the list of the compiled source files in a file

[dbitouze]

Is your feature request related to a problem? Please describe. During a HTML build, I need to obtain the list of the compiled (.md) source files in order to afterwards apply a script to the corresponding generated (.html) files. AFAICS, the only way to get this list is to use the -vv option but, this time, the output is very, very (understand: too) verbose.

Describe the solution you'd like I'd like a (say -f ⟨file⟩) option that writes the list of the compiled source files to the given ⟨file⟩ (just as -w ⟨file⟩ writes warnings (and errors) to the given ⟨file⟩).

Describe alternatives you've considered I considered sphinx-build source build/html -j auto -vv > log.txt but:

1. I can't see the result of the compilation in the output,
2. log.txt is too much verbose.

[picnixz]

This is something I would like to say "yes". I assume you want this for autodoc where you could then change manually whatever autodoc has written right?

For that, we need to modify the documenters that are responsible for generating the content. We (at least I) plan to upgrade autodoc to something much more robust and customizable so it'll probably be part of a huge todo list.

EDIT: actually I think I misunderstood. You only want the filenames? if so, you should use your own writer class if you want to mess with the HTML content. Or you could do a grep on the log itself. If you want the content of the compiled files then it's my proposal.

[dbitouze]

This is something I would like to say "yes". I assume you want this for autodoc where you could then change manually whatever autodoc has written right?

Actually, no, as you realized later :wink:

EDIT: actually I think I misunderstood. You only want the filenames? if so, you should use your own writer class if you want to mess with the HTML content.

Outch! Beyond my scope, I'm afraid.

Or you could do a grep on the log itself.

Do you mean something like make html | grep "docnames to write"? If so, that's not what I'm after since the output would miss the warnings (and errors) of the corresponding compilation.

If you want the content of the compiled files then it's my proposal.

Not sure what you mean here. In fact, I'd like both:

• the list of the (possibly numerous in our case) compiled files store in a ⟨file⟩,
• the normal output of a make html compilation in order to be able to see its warnings (and errors).

[picnixz]

Ah I see. Actually, you might not necessarily have a 1-to-1 mapping from the files Sphinx reads to its outputs. Also, by 'compiled' files, I'm not sure what you want because for instance when you have some .. automodule:: MyModule in a file, what is being 'compiled' is really that file and not the corresponding Python file.

If you need to manipulate what is being written by Sphinx, I can only see an extension approach. If you only want to see what failed and where or what has been written etc, the best way to do it is to have a verbose output and work on that output directly.

[dbitouze]

Ah I see. Actually, you might not necessarily have a 1-to-1 mapping from the files Sphinx reads to its outputs. Also, by 'compiled' files, I'm not sure what you want because for instance when you have some .. automodule:: MyModule in a file, what is being 'compiled' is really that file and not the corresponding Python file.

What I mean by "compiled" is the .rst or .md source files converted to .html ones during the make html process.

If you need to manipulate what is being written by Sphinx, I can only see an extension approach.

Sigh... :wink:

If you only want to see what failed and where or what has been written etc, the best way to do it is to have a verbose output and work on that output directly.

OK, I'll give some tests, thanks!

[picnixz]

What I mean by "compiled" is the .rst or .md source files converted to .html one dureing the make html process.

I think we could add a logger message to help you and you would catch whatever we say? like converting [the source] into [the output]. Many warnings have their location so you could still filter warnings + intersect with the sources being processed.

I don't know whether we have things like this but I'd say this feature is incorporated in a more global issue where logger's messages must be improved in general.