Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rework how user-specified doclet and layout modules are managed #25

Merged
merged 1 commit into from
Jun 3, 2022

Conversation

dumbbell
Copy link
Collaborator

@dumbbell dumbbell commented Jun 3, 2022

The previous approach had several major issues that couldn't be easily fixed:

  1. I understood how edoc_{doclet,layout}_chunks worked incorrectly. I thought that they would generate both the HTML documentation and the EEP-48 doc chunks. That's not the case and they only generate doc chunks. So to get both, we need to run EDoc with edoc_doclet and edoc_layout in addition to the configured modules.

  2. Calling edoc_*_chunks and ignoring the return values (because we want to call edoc_* too) broke doc chunks. So it's not possible to chain EDoc backend modules from the backend modules themselves.

  3. The way we overrode EDoc options in the Rebar state was ineffective.

    Rebar supports project- and app-level configurations. The app-level configuration defaults to the project-level one. The edoc Rebar command merges them to create the final list of options.

    Because of this, we ended up with duplicated options for those we override in this plugin. For instance, we got two doclet modules in the options list: one from the project-level configuration (set by this plugin), one from the app-level configuration (inherited from the project-level configuration before we modify it). And the app-level configuration took precedence, meaning that our backend modules were not used.

This patch brings a new design.

First, the loop over project apps now overrides settings in the app-level configuration. The same settings are removed from the project-level configuration. This ensures that the edoc command will get the options we override from the app-level configuration only.

Second, instead of calling the user-configured backend modules from our own modules, we simply call the edoc Rebar command twice: once for each set of modules. If the user is using default backends, we simply call edoc once for this plugin.

The previous approach had several major issues that couldn't be easily
fixed:

1.  I understood how `edoc_{doclet,layout}_chunks` worked incorrectly. I
    thought that they would generate both the HTML documentation and the
    EEP-48 doc chunks. That's not the case and they only generate doc
    chunks. So to get both, we need to run EDoc with `edoc_doclet` and
    `edoc_layout` in addition to the configured modules.

2.  Calling `edoc_*_chunks` and ignoring the return values (because we
    want to call `edoc_*` too) broke doc chunks. So it's not possible to
    chain EDoc backend modules from the backend modules themselves.

3.  The way we overrode EDoc options in the Rebar state was ineffective.

    Rebar supports project- and app-level configurations. The app-level
    configuration defaults to the project-level one. The `edoc` Rebar
    command merges them to create the final list of options.

    Because of this, we ended up with duplicated options for those we
    override in this plugin. For instance, we got two `doclet` modules
    in the options list: one from the project-level configuration (set
    by this plugin), one from the app-level configuration (inherited
    from the project-level configuration before we modify it). And the
    app-level configuration took precedence, meaning that our backend
    modules were not used.

This patch brings a new design.

First, the loop over project apps now overrides settings in the
app-level configuration. The same settings are removed from the
project-level configuration. This ensures that the `edoc` command will
get the options we override from the app-level configuration only.

Second, instead of calling the user-configured backend modules from our
own modules, we simply call the `edoc` Rebar command twice: once for
each set of modules. If the user is using default backends, we simply
call `edoc` once for this plugin.
@dumbbell dumbbell added the bug Something isn't working label Jun 3, 2022
@dumbbell dumbbell self-assigned this Jun 3, 2022
@dumbbell dumbbell marked this pull request as ready for review June 3, 2022 12:17
@dumbbell dumbbell merged commit 53de439 into main Jun 3, 2022
@dumbbell dumbbell deleted the rework-edoc-backends-chaining branch June 3, 2022 12:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants