Page MenuHomePhabricator

The Doxygen version in CI parses README files as garbled C.
Closed, ResolvedPublic

Description

For example https://doc.wikimedia.org/mediawiki-core/master/php/README.html , it has garbled "Variables" and "Variables Documentation" sections documenting a details variable, etc. Likewise other README files like maintenance/README. Other doxygen pages even link to these bogus variable definitions, e.g. "details" here. This is by design according to the doxygen FAQ:

[prior to 1.8.8] doxygen parsed all files with an unknown extension as C files which could lead to undesired results

includes/filebackend/README adapts to this behavior by starting with /*! and including Doxygen directives, but changing every README to appear as C seems like overkill.
Instead, Extension mapping says we can specify the mapping for .no_extension. Most README files with no extension are just plaintext, but insanely, doxygen doesn't support a text file format (it's even processing .txt files as C, e.g. APACHE-LICENSE-2.0.txt). So perhaps EXTENSION_MAPPING = ".no_extension=md" (markdown) is the best.

Note the behavior will change when and CI updates to a newer Doxygen version. In my local tests with doxygen 1.8.9.1, all README files become just "Go to the source code of this file" links.

The README in the core's root directory is the exception; it's actually wikitext. gerrit 27117 creates a symlink README.mediawiki because github supports the .mediawiki extension, unlike doxygen.

Event Timeline

Spage raised the priority of this task from to Needs Triage.
Spage updated the task description. (Show Details)
Spage added subscribers: Spage, hashar.
Restricted Application added a project: Documentation. · View Herald TranscriptJul 17 2015, 3:24 AM
Restricted Application added a subscriber: Aklapper. · View Herald Transcript
hashar triaged this task as Low priority.Aug 24 2015, 1:59 PM
hashar added a comment.EditedSep 3 2015, 1:24 PM

The https://integration.wikimedia.org/ci/job/mediawiki-core-doxygen-publish/ mediawiki-core-doxygen-publish Jenkins job runs on Trusty which comes with Doxygen version 1.8.6.

It supports markdown at least, so EXTENSION_MAPPING = ".no_extension=md" looks like a good idea :-} Can be changed in mediawiki/core.git maintenance/Doxyfile.

For wiki text markup, we could invoke MediaWiki parser to generate the HTML. That is a bit scary though ;-}

hashar set Security to None.

Dropping Continuous-Integration-Config , I don't think there is much to do on Jenkins side.

Doxygen version 1.8.6 ... supports markdown at least, so EXTENSION_MAPPING = ".no_extension=md" looks like a good idea :-} Can be changed in mediawiki/core.git maintenance/Doxyfile.

Sounds neat, but would that break includes/filebackend/README, which begins with a C comment and has directives? We could rename text files using Doxygen directives to README.c (or .php) to preserve this.

I think Git files with no extension are a bad idea and we should identify all file types (T116690: Give text files in Git correct extensions); I just wrote Manual:Coding conventions#Text files. So a related issue is what's the best doxygen processing for actual plain .txt in doxygen that's compatible with their handing in diffusion and GitHub, which seems to be just show the raw file.

Sounds neat, but would that break includes/filebackend/README, which begins with a C comment and has directives? We could rename text files using Doxygen directives to README.c (or .php) to preserve this.

I (or Aaron) made that one a Doxygen/C like in attempt to produce nice documentation and the result is generated at https://doc.wikimedia.org/mediawiki-core/master/php/group__FileBackend.html#file_backend_design

With Doxygen markdown support ( doc: https://www.stack.nl/~dimitri/doxygen/manual/markdown.html ). Maybe it will manage to recongizes the class / methods being mentioned as plain text, else we would need to
use the markdown syntax to create the references.