How to avoid duplicate documentation?

[gnawin]

Referring to the PR #483, I think it would be good practice to reference docstring directly without creating duplicate content.

I would think using @docs is the way to go https://documenter.juliadocs.org/stable/man/syntax/#@docs-block.

But I got an error msg below:

┌ Error: duplicate docs found for 'TulipaEnergyModel.EnergyProblem' in src\reference.md:14-16
│ ```@autodocs
│ Modules = [TulipaEnergyModel]
│ ```
└ @ Documenter C:\Users\wangn\.julia\packages\Documenter\1HwWe\src\utilities\utilities.jl:44
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
ERROR: LoadError: `makedocs` encountered an error [:autodocs_block] -- terminating build before rendering.`

It suggests it conflicts with the use of @autodocs when we create the table of contents for the documentation.

For this PR, it should be fine, but for any future docs it would be nice to make it work. I don't see a direct solution to this, or maybe I missed something. Any ideas?

[abelsiqueira]

I don't understand what was done. Where was it duplicated?

[abelsiqueira]

Ah, got it. Checked online and apparently you can do this:

TulipaEnergyModel.EnergyProblem

The canonical=false makes it so that this is considered the "extra" docs, and the @autodocs one is the official place. If it works, I think it is what we want.

[gnawin]

Works already!

But I was expecting to only get the text, not like the reference-style, with the box and names etc. The way it is now is inconsistent with the rest.

[gnawin]

another pic showing how it looks with the rest:

[abelsiqueira]

Maybe something like

@doc EnergyProblem

might work? Would need to test some variation of this. @doc is part of Base, I think.

[gnawin]

Thank you. I've tried some workarounds (see below), but still not as satisfactory. For the time being, I will not block the PR #483.

.

Would be happy if we continue exploring this topic.

[clizbe]

Works already!

But I was expecting to only get the text, not like the reference-style, with the box and names etc. The way it is now is inconsistent with the rest.

I prefer this one - maybe we can just remove the collapse arrow?

[gnawin]

yes, but how...?

[clizbe]

I asked Julia:
https://discourse.julialang.org/t/fix-nesting-or-disable-expansion-arrow-using-documenter-jl/117424

Otherwise I guess it should just be nested since it's better for maintenance.

[gnawin]

Thanks for posting!