Documentation Building Errors

[bennettm]

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

1. Warnings about unexpected Julia interpolation of type Symbol in the Markdown:

Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :\
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215
┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :/
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/nQAq5/src/html/HTMLWriter.jl:2215

2. A list of functions did not get documented successfully when documentation is being built. Here is the output:

[ Info: CheckDocument: running document checks.
┌ Warning: 120 docstrings not included in the manual:
│└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.

3. These warnings are about duplicate docs:

Warning: duplicate docs found for 'DOLPHYN.hydro_inter_period_linkage!' in src/hydro_res.md:2-8
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = [
│     "GenX/src/model/resources/hydro/hydro_res.jl",
│     "GenX/src/model/resources/hydro/hydro_inter_period_linkage.jl"
│ ]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.cap_reserve_margin!' in src/slack_variables_overview.md:60-63
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["cap_reserve_margin.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.load_cap_reserve_margin!' in src/slack_variables_overview.md:60-63
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["cap_reserve_margin.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.load_cap_reserve_margin_trans!' in src/slack_variables_overview.md:60-63
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["cap_reserve_margin.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.load_co2_cap!' in src/slack_variables_overview.md:67-70
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["co2_cap.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.energy_share_requirement!' in src/slack_variables_overview.md:74-77
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["energy_share_requirement.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.load_energy_share_requirement!' in src/slack_variables_overview.md:74-77
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["energy_share_requirement.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.load_minimum_capacity_requirement!' in src/slack_variables_overview.md:81-84
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["minimum_capacity_requirement.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.minimum_capacity_requirement!' in src/slack_variables_overview.md:81-84
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["minimum_capacity_requirement.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.configure_solver' in src/solvers.md:2-5
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["configure_solver.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.configure_clp' in src/solvers.md:8-11
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["configure_clp.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.configure_cbc' in src/solvers.md:14-17
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["configure_cbc.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.configure_highs' in src/solvers.md:20-23
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["configure_highs.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.configure_gurobi' in src/solvers.md:26-29
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["configure_gurobi.jl"]
│ ```
│   :autodocs_block = :autodocs_block
└ @ Documenter ~/.julia/packages/Documenter/nQAq5/src/utilities/utilities.jl:46
┌ Warning: duplicate docs found for 'DOLPHYN.configure_cplex' in src/solvers.md:32-35
│ ```@autodocs
│ Modules = [DOLPHYN]
│ Pages = ["configure_cplex.jl"]
│ ```
│   :autodocs_block = :autodocs_block

Expected Behavior

Expect all functions with docstring should be included in the manual. They should not show up in the output of documentation building as "not included in the manual".

Error: "Unexpected Julia interpolation of type Symbol in the Markdown." should not be in the output.

Make sure all functions have docstring to show up in the final documentation.

Steps To Reproduce

1. In DOLPHYN folder, run julia --project=docs docs/make.jl
2. In the output at the end of this documentation building, you will see a warning about such functions.

Environment

- OS: MacBook Pro Ventura 13.6
- Julia version: 1.9
- Solver: Gurobi
- Solver version: 10.0.3

Manifest.toml file

Manifest.toml.txt

Anything else?