About non canonical bibliography inconsistencies (to autodocs)

[kellertuer]

(Sorry for posting yet another issue)

I noticed two interesting things about non canonical bibliographies, i.e. when I want to have a “Literature” section at the end of my documentation page.

assume the following: I have a source file called src/functions/proximal_maps.jl whose functions shall be documented on a page /functions/proximal_maps.html so I have a file docs/src/functions/proximal_maps.md to do that. This file could in a minimal sense look like in

# [Proximal Maps](@id proximalMapFunctions)

```@autodocs
Modules = [Manopt]
Pages   = ["proximal_maps.jl"]
```

# Literature

```@bibliography
Pages = ["functions/proximal\_maps.md"]
Canonical=false
```

There is a few things to note

1. for @autodocs a file name is enough, while @bibliography needs the complete relative path
2. for @autodocs I do not have to escape the _, for @bibliography I do.
3. For @bibliography it would be nice to have a way to say (maybe something similarly short as the nice * “I want all references from this markdown file”, because this relative path to the markdown file I am in is currently something I type at several pages.

Besides these three points, the workflow overall is quite nice.

[goerz]

1. for @autodocs a file name is enough, while @bibliography needs the complete relative path

I agree that @autodocs and @biliography, and similar Documenter blocks should be consistent in how the Pages field is treated.

2. for @autodocs I do not have to escape the _, for @bibliography I do.

Yes, I consider that a bug. Same as in #14 (comment), I would very much like to handle the citations without the Markdown parser getting in the way, if at all possible. It seems like @autodocs manages to that, so it does seem like it is!

3. For @bibliography it would be nice to have a way to say (maybe something similarly short as the nice * “I want all references from this markdown file”, because this relative path to the markdown file I am in is currently something I type at several pages.

That does seem like it would be a convenient feature, although I'm not sure about the syntax for that. Maybe Pages = ["%"], borrowing vim's % variable for "the current file". On the other hand, unless that was also supported in Documenter's other Pages fields, it would again be inconsistent.

[kellertuer]

2 might actually just have been a temporary thing, it seems to work by now – but 1) and 3) remain.
And thanks for eagerly answering all my questions and remarks.
I did rewrite some parts of my docs already and really love the result – I hope to not have too many further issues I run into ;)

[fredrikekre]

Pages = [@__FILE__] perhaps.

[goerz]

For @autodocs specifically, Documenter just compares the entries in Pages to the path of the page containing the block, using endswith (after normpath), see the documentation and the implementation.

For other uses of Pages like @index and @contents, it seems like a page string is checked against Pages with exact equality (page in Pages, via _isvalid).

• for @index: page = relpath(doc.page.build, dirname(index.build)) for the various doc objects that are candidates for the index, and where index.build is the path of the file containing the @index block.
• for @contents: page = relpath(anchor.file, dirname(contents.build)) for the various heading anchors in the project.

So it seems like the values in Pages in both cases are expected to be paths relative to the folder containing the file containing the @index/@contents block. This isn't explicitly documented, but makes a lot of sense. Small detail: I'm not quite sure where Documenter deals with Windows path separators. It seems like normpath should be applied to the Pages fields. This happens for @autodocs, but I'm not seeing it for @index/@contents.

In the current implementation of the @bibliography block, I'm checking the values in Pages exactly against the values in the internal doc.blueprint.pages. Those are determined by the pagekey function, which seems to be a relative path to the docs/src directory. I didn't put very much thought into this implementation at the time, so this is not an explicit design choice (and thus, I would consider fixing this behavior is a bugfix, not a breaking change).

There are some other issues with the current implementation: listing a page that doesn't exist throws a KeyError, when it should either be silently ignored, or maybe emit a warning if I can manage that.

In any case, the Pages in @bibliography feels conceptually closer to Pages in @index and @contents, not so much the Pages in @autodocs (note that @bibliography only takes .md files, whereas @autodocs also takes .jl files, which is why relative paths don't really make sense there.) Thus, to be consistent, @bibliograhy should adopt the same behavior as @index/@contents where the names are relative to the folder containing the file that contains the @biliography block. Does that seem reasonable?

I'm also definitely open to adding support for @__FILE__, although none of the other blocks in Documenter support that (maybe they should!). Implementation details: Already now, the right-hand-side of the Pages attribute is eval'ed, so it can in fact be arbitrary code. If you put @__FILE__ in there, it happens to evaluate to the string "none". There's probably nothing I can do about that at the eval level, but I don't see a problem with catching "none" and replacing that with the current file name.