ocamlpro / digodoc

Dig into an opam switch for doc

digodoc

The Digodoc library scans opam switches and builds maps of them. It is used to build documentation websites, such as https://docs.ocaml.pro

• Website: https://ocamlpro.github.io/digodoc
• General Documentation: https://ocamlpro.github.io/digodoc/sphinx
• API Documentation: https://ocamlpro.github.io/digodoc/doc
• Sources: https://github.com/ocamlpro/digodoc

digodoc's Issues

windows' and macos' CI fail

1. opam do not support command depext within macos' CI:

opam: unknown command `depext'.
Usage: opam COMMAND ...
Try `opam --help' for more information.
Error: Process completed with exit code 2.

2. windows CI needs installation of packages gmp and system:pkgconf

The packages you requested declare the following system dependencies. Please make sure they are installed before retrying:
    gmp system:pkgconf

Type indexation considers too many artefacts

It seems that type indexation makes some extra indexation steps that weren't envisaged:

1. Indexation types of classes, that is useless (due to existing separated class index) and doesn't provide correct link to the type in documentation page. Example:

(#in_obj_channel)
TYPE_ABSTRACT
in_obj_channel

This is an indexation entry for class in_obj_channel within moduleCsv inside package csv.
2. Indexation of corresponding class artifacts (values and methods)

handle HTML more precisely

see #60 (comment)

Split index generation from page generation

Currently, the index is generated during the same pass as other pages. So, there is no way to merge package documentations coming from multiple switches. Instead, we should save the package documentations first, with enough information for a second, independent, pass to generate the 4 indexes.

Note that, though it will be easy to regenerate the indexes for OPAM., LIBRARY. and META., only independent modules have a MODULE. entry. So, we need to find another solution for modules that are included in libraries.

mld files are not rendered

It seems these files are currently not rendered. That's a problem for my libraries which often have such files.

Also it would be nice to honour the odig convention which allows packages to customize part of the package page landing page via the index.mld file of the package. In my packages these files also have important bits for end-users (see e.g. odig's brr's package page).

cma-only libraries not taken into account

It seems that cma-only libraries are ignored.

For instance, the OPAM package num installs three METAs :

• num (which is virtual)
• num.core, containing the library nums.(cma|cmxa|cmxs)
• num-top, containing the library num_top.cma

The generated documentation for the OPAM package correctly mentions the three METAs, but only mentions the nums library.

Add a link to the source archive in opam packages

Module associated to package

Module should be correctly associated to a package inside in_packs input.

mli-only module never considered a dependency by ocamlobjinfo

The ocamlbuildlib.cmxa library uses signatures.mli, according to its source files, however ocamlobjinfo never lists this dependency. The .cmi and .cmti files for signatures are also present.

I don't know if this is related, but the Signatures interface only appears in include statements.

Change typing for module extensions from StringSet.t to StringMap.t

Some unsuspected crash has occured when mapping modules to their respective package directory.

Indeed some modules appear in subdirectories of that package (.private/ for example) and there mapping to that package is erroneous, said module being mapped the package dir, instead of, to keep previous example, .private.

We have noticed small discrepancies between our expectations and the reality of some .changes files under .opam_switch/install of the opam config subtree.

This issue and #51 are correlated

Add local search possibility within module pages

Add local search possibility within module pages, when modules will be organized better (without redundant __ as desribed here)

Incorrect documentation link for embedded modules

Embedded modules are treated sometimes incorrectly and with additional __. This implies redundant module page with same __ at the end of the module name. That should be analysed and fixed.

Default filter deducted from arguments

While clicking on "Update filters" button on the Advanced Search page, previously used filters should be opened by default instead of entry filters.

Extend list of supported formats in sources tab

Consider extending the list of supported formats in the source tab with the following:

• .md files
• image formats (JPEG/PNG/...)
• .c and .h files
• binary files

Which are all rendered in a raw manner, for now.

Replace "Modules" by "Documentation on Modules"

Assign to each extension of a given module its subdirectories if any exist

This would allow prevention of errors for a given module that has different subdirectories hiding a set of extensions.

Fix links in HTML code in MD files

HTML code found in Markdown files isn't patched when generating sources and fixing static links.

Example:
Alcotest README.md file

### Examples

A simple example (taken from `examples/simple.ml`):

<p align="center"><img src="./.meta/ok.png" width="65%"></p>

This static link won't be patched and rendered in digodoc's Sources tab

css templates overhaul

Consider revisiting the overall esthetic and interface of generated doc pages.

• make it look even prettier, coloring, background and whatnot

• improve interfaces for a clearer, properly better user experience

Patch broken html relative links in Markdown sources

#50 has revealed the need for a patching of relative links in generated markdown .html files.