Documenter warnings

ufechner7 · August 28, 2022, 5:12pm

When I try to build the documentation of the package GitHub - ufechner7/KiteUtils.jl: Utilities for kite power system simulations using the command:

include("docs/make.jl")

I get the following warnings:

First warning:

[ Info: Precompiling KiteUtils [90980105-b163-44e5-ba9f-8b1c83bb0533]
┌ Warning: Unable to determine HTML(edit_link = ...) from remote HEAD branch, defaulting to "master".
│ Failed to parse the `git remote` output. Set JULIA_DEBUG=Documenter to see the output.
│ Unless this is due to a configuration error, the relevant variable should be set explicitly.
└ @ Documenter.Utilities ~/.julia/packages/Documenter/yf96B/src/Utilities/Utilities.jl:832

Second warning:

┌ Warning: duplicate docs found for 'Logger{P, Q}' in `@docs` block in src/types.md:14-19
│ ```@docs
│ MyFloat
│ SysState{P}
│ SysLog{P}
│ Logger{P, Q}
│ ```
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Utilities/Utilities.jl:34

Regarding the second warning, I have the code:

"""
    mutable struct Logger{P, Q}

Struct to store a simulation log. P is number of points of the tether, segments+1 and 
Q is the number of time steps that will be pre-allocated.

$(TYPEDFIELDS)
"""
@with_kw mutable struct Logger{P, Q}
...

and

"""
    Logger(P, steps)

Creates a Logger object for kite power systems with `P point masses which can store up to `steps` number of time steps.
"""
function Logger(P, steps)
    logger = Logger{P, steps}()
    logger
end

in the file KiteUtils.jl/logger.jl at main · ufechner7/KiteUtils.jl · GitHub

Is there anything wrong with this code?

SteffenPL · August 28, 2022, 5:37pm

Could the first problem be that the main branch is called main instead of master?

As written here:

┌ Warning: Unable to determine HTML(edit_link = ...) from remote HEAD branch, defaulting to "master".

digital_carver · August 28, 2022, 5:42pm

The code is looking for any line with HEAD branch: followed by a branch name, doesn’t specifically assume a particular name (and only prints this warning if it can’t find such a line at all). Also, if that was an issue, there would likely be a lot more packages affected by this I think, and it would’ve been noticed a lot earlier.

Can you try running with this env variable set? (JULIA_DEBUG=Documenter julia)

I’m curious what the git remote show output is that leads to this error. Cloning the package locally and trying out the command (git remote show origin), the output does contain a HEAD branch: line in my case.

ufechner7 · August 28, 2022, 5:48pm

ufechner@tuxedi:~/repos/KiteUtils.jl$ JULIA_DEBUG=Documenter julia --project
               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.7.3 (2022-05-06)
 _/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
|__/                   |

julia> include("docs/make.jl")
┌ Debug: Creating documentation metadata dictionary (META=##docmeta#291) in KiteUtils
└ @ Documenter.DocMeta ~/.julia/packages/Documenter/yf96B/src/DocMeta.jl:36
┌ Warning: Unable to determine HTML(edit_link = ...) from remote HEAD branch, defaulting to "master".
│ Failed to parse the `git remote` output. Set JULIA_DEBUG=Documenter to see the output.
│ Unless this is due to a configuration error, the relevant variable should be set explicitly.
└ @ Documenter.Utilities ~/.julia/packages/Documenter/yf96B/src/Utilities/Utilities.jl:832
┌ Debug: stdout from setenv(`/usr/bin/git remote show origin`,["PATH=/home/ufechner/.local/bin:/home/ufechner/.cargo/bin:/home/ufechner/.cargo/bin:/home/ufechner/.local/bin:/home/ufechner/.local/bin:/home/ufechner/.cargo/bin:/home/ufechner/.cargo/bin:/home/ufechner/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/ufechner/.dotnet/tools:/home/ufechner/.dotnet/tools", "DEFAULTS_PATH=/usr/share/gconf/ubuntu.default.path", "QT_ACCESSIBILITY=1", "DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus", "XDG_SEAT_PATH=/org/freedesktop/DisplayManager/Seat0", "XDG_SESSION_DESKTOP=ubuntu", "GIT_TERMINAL_PROMPT=0", "SSH_AGENT_PID=2712", "XDG_SESSION_TYPE=x11", "GIT_TEMPLATE_DIR=/usr/share/git-core/templates", "USER=ufechner", "XDG_CONFIG_DIRS=/etc/xdg/xdg-ubuntu:/etc/xdg:/usr/share/kubuntu-default-settings/kf5-settings", "LESSCLOSE=/usr/bin/lesspipe %s %s", "QT_IM_MODULE=ibus", "PAM_KWALLET5_LOGIN=/run/user/1000/kwallet5.socket", "LC_TIME=nl_NL.UTF-8", "LC_NUMERIC=nl_NL.UTF-8", "LC_MEASUREMENT=nl_NL.UTF-8", "GDK_BACKEND=x11", "GNOME_SHELL_SESSION_MODE=ubuntu", "GDMSESSION=ubuntu", "LC_TELEPHONE=nl_NL.UTF-8", "VSCODE_GIT_ASKPASS_NODE=/usr/share/code/code", "LESSOPEN=| /usr/bin/lesspipe %s", "XDG_DATA_DIRS=/usr/share/ubuntu:/usr/local/share:/usr/share:/var/lib/snapd/desktop", "SHELL=/bin/bash", "GJS_DEBUG_OUTPUT=stderr", "XAUTHORITY=/home/ufechner/.Xauthority", "VSCODE_GIT_ASKPASS_EXTRA_ARGS=--ms-enable-electron-run-as-node", "XDG_MENU_PREFIX=gnome-", "VSCODE_GIT_IPC_HANDLE=/run/user/1000/vscode-git-5255b2ec0a.sock", "GIT_SSH_COMMAND=ssh -o \"BatchMode yes\"", "GTK_MODULES=gail:atk-bridge:appmenu-gtk-module", "MANAGERPID=2552", "SESSION_MANAGER=local/tuxedi:@/tmp/.ICE-unix/2746,unix/tuxedi:/tmp/.ICE-unix/2746", "XMODIFIERS=@im=ibus", "JULIA_DEBUG=Documenter", "HOME=/home/ufechner", "TERM=xterm-256color", "GTK_PATH=/usr/lib/x86_64-linux-gnu/gtk-3.0:/home/ufechner/.local/bin:/home/ufechner/.cargo/bin:/home/ufechner/.cargo/bin:/home/ufechner/.local/bin:/home/ufechner/.local/bin:/home/ufechner/.cargo/bin:/home/ufechner/.cargo/bin:/home/ufechner/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/ufechner/.dotnet/tools:/home/ufechner/.dotnet/tools", "COLORTERM=truecolor", "GTK2_MODULES=overlay-scrollbar", "KIGITHUB=https://github.com/KiCad", "GIT_ASKPASS=/usr/share/code/resources/app/extensions/git/dist/askpass.sh", "IM_CONFIG_PHASE=1", "INVOCATION_ID=896817a9e7c5418ea5bc4710210dcca6", "KICAD_PATH=/usr/share/kicad", "XDG_CURRENT_DESKTOP=Unity", "LANG=de_DE.UTF-8", "LOGNAME=ufechner", "GNOME_DESKTOP_SESSION_ID=this-is-deprecated", "LC_MONETARY=nl_NL.UTF-8", "SHLVL=1", "XDG_RUNTIME_DIR=/run/user/1000", "SSH_AUTH_SOCK=/run/user/1000/keyring/ssh", "DESKTOP_SESSION=ubuntu", "GDM_LANG=de_DE", "LC_ADDRESS=nl_NL.UTF-8", "LC_PAPER=nl_NL.UTF-8", "CHROME_DESKTOP=code-url-handler.desktop", "_=/home/ufechner/.local/bin/julia", "GPG_AGENT_INFO=/run/user/1000/gnupg/S.gpg-agent:0:1", "LIBVIRT_DEFAULT_URI=qemu:///system", "GIO_LAUNCHED_DESKTOP_FILE=/usr/share/applications/code.desktop", "TERM_PROGRAM_VERSION=1.70.2", "PWD=/home/ufechner/repos/KiteUtils.jl", "XDG_SESSION_CLASS=user", "DISPLAY=:0", "TERM_PROGRAM=vscode", "GJS_DEBUG_TOPICS=JS ERROR;JS LOG", "VSCODE_GIT_ASKPASS_MAIN=/usr/share/code/resources/app/extensions/git/dist/askpass-main.js", "LANGUAGE=de_DE", "XDG_GREETER_DATA_DIR=/var/lib/lightdm-data/ufechner", "XDG_SESSION_PATH=/org/freedesktop/DisplayManager/Session0", "ORIGINAL_XDG_CURRENT_DESKTOP=ubuntu:GNOME", "MANDATORY_PATH=/usr/share/gconf/ubuntu.mandatory.path", "LC_NAME=nl_NL.UTF-8", "JOURNAL_STREAM=9:53440", "LC_IDENTIFICATION=nl_NL.UTF-8", "GIO_LAUNCHED_DESKTOP_FILE_PID=22869", "LS_COLORS=rs=0:di=01;34:ln=01;36:mh=00:pi=40;33:so=01;35:do=01;35:bd=40;33;01:cd=40;33;01:or=40;31;01:mi=00:su=37;41:sg=30;43:ca=30;41:tw=30;42:ow=34;42:st=37;44:ex=01;32:*.tar=01;31:*.tgz=01;31:*.arc=01;31:*.arj=01;31:*.taz=01;31:*.lha=01;31:*.lz4=01;31:*.lzh=01;31:*.lzma=01;31:*.tlz=01;31:*.txz=01;31:*.tzo=01;31:*.t7z=01;31:*.zip=01;31:*.z=01;31:*.dz=01;31:*.gz=01;31:*.lrz=01;31:*.lz=01;31:*.lzo=01;31:*.xz=01;31:*.zst=01;31:*.tzst=01;31:*.bz2=01;31:*.bz=01;31:*.tbz=01;31:*.tbz2=01;31:*.tz=01;31:*.deb=01;31:*.rpm=01;31:*.jar=01;31:*.war=01;31:*.ear=01;31:*.sar=01;31:*.rar=01;31:*.alz=01;31:*.ace=01;31:*.zoo=01;31:*.cpio=01;31:*.7z=01;31:*.rz=01;31:*.cab=01;31:*.wim=01;31:*.swm=01;31:*.dwm=01;31:*.esd=01;31:*.jpg=01;35:*.jpeg=01;35:*.mjpg=01;35:*.mjpeg=01;35:*.gif=01;35:*.bmp=01;35:*.pbm=01;35:*.pgm=01;35:*.ppm=01;35:*.tga=01;35:*.xbm=01;35:*.xpm=01;35:*.tif=01;35:*.tiff=01;35:*.png=01;35:*.svg=01;35:*.svgz=01;35:*.mng=01;35:*.pcx=01;35:*.mov=01;35:*.mpg=01;35:*.mpeg=01;35:*.m2v=01;35:*.mkv=01;35:*.webm=01;35:*.ogm=01;35:*.mp4=01;35:*.m4v=01;35:*.mp4v=01;35:*.vob=01;35:*.qt=01;35:*.nuv=01;35:*.wmv=01;35:*.asf=01;35:*.rm=01;35:*.rmvb=01;35:*.flc=01;35:*.avi=01;35:*.fli=01;35:*.flv=01;35:*.gl=01;35:*.dl=01;35:*.xcf=01;35:*.xwd=01;35:*.yuv=01;35:*.cgm=01;35:*.emf=01;35:*.ogv=01;35:*.ogx=01;35:*.aac=00;36:*.au=00;36:*.flac=00;36:*.m4a=00;36:*.mid=00;36:*.midi=00;36:*.mka=00;36:*.mp3=00;36:*.mpc=00;36:*.ogg=00;36:*.ra=00;36:*.wav=00;36:*.oga=00;36:*.opus=00;36:*.spx=00;36:*.xspf=00;36:", "OPENBLAS_MAIN_FREE=1"]; dir="/home/ufechner/repos/KiteUtils.jl/docs"):
│ * Remote-Repository origin
│   URL zum Abholen: https://ghp_-----------@github.com/ufechner7/KiteUtils.jl.git
│   URL zum Versenden: https://ghp_--------------@github.com/ufechner7/KiteUtils.jl.git
│   Hauptbranch: main
│   Remote-Branches:
│     cleanup                                                      gefolgt
│     compathelper/new_version/2021-12-26-00-54-41-793-02440701729 gefolgt
│     compathelper/new_version/2021-12-26-00-54-56-279-00567882123 gefolgt
│     compathelper/new_version/2021-12-27-00-52-14-885-00853158327 gefolgt
│     compathelper/new_version/2021-12-28-00-51-32-782-04093324540 gefolgt
│     compathelper/new_version/2022-05-27-01-18-02-453-03148833034 gefolgt
│     docu                                                         gefolgt
│     gh-pages                                                     gefolgt
│     main                                                         gefolgt
│   Lokaler Branch konfiguriert für 'git pull':
│     main führt mit Remote-Branch main zusammen
│   Lokale Referenz konfiguriert für 'git push':
│     main versendet nach main (aktuell)
│ 
└ @ Documenter.Utilities ~/.julia/packages/Documenter/yf96B/src/Utilities/Utilities.jl:837
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
┌ Debug: Running doctests.
└ @ Documenter.DocTests ~/.julia/packages/Documenter/yf96B/src/DocTests.jl:47
[ Info: ExpandTemplates: expanding markdown templates.
┌ Debug: pages
│   keys(doc.blueprint.pages) = KeySet for a Dict{String, Documenter.Documents.Page} with 5 entries. Keys: …
│   priority_pages = String[]
│   normal_pages = 5-element Vector{String}: …
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:36
┌ Debug: Running ExpanderPipeline on examples.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:39
┌ Debug: Evaluating @meta block:
│ CurrentModule = KiteUtils
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:261
┌ Debug: Running ExpanderPipeline on functions.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:39
┌ Debug: Evaluating @meta block:
│ CurrentModule = KiteUtils
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:261
┌ Debug: Evaluating @docs block:
│ set_data_path
│ load_settings
│ update_settings
│ copy_settings
│ se
│ se_dict
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:287
┌ Debug: Evaluating @docs block:
│ demo_state
│ demo_state_4p
│ demo_syslog
│ demo_log
│ get_particles
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:287
┌ Debug: Evaluating @docs block:
│ Logger
│ log!
│ load_log
│ save_log
│ export_log
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:287
┌ Debug: Evaluating @docs block:
│ rot3d(ax, ay, az, bx, by, bz)
│ rot(pos_kite, pos_before, v_app)
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:287
┌ Debug: Evaluating @docs block:
│ fromENU2EG
│ fromEG2W
│ fromW2SE
│ fromKS2EX
│ fromEX2EG
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:287
┌ Debug: Evaluating @docs block:
│ calc_elevation
│ calc_azimuth
│ calc_heading
│ calc_course
│ calc_heading_w
│ azimuth_east
│ ground_dist
│ acos2
│ initial_kite_ref_frame
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:287
┌ Debug: Running ExpanderPipeline on index.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:39
┌ Debug: Evaluating @meta block:
│ CurrentModule = KiteUtils
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:261
┌ Debug: Running ExpanderPipeline on reference_frames.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:39
┌ Debug: Evaluating @meta block:
│ CurrentModule = KiteUtils
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:261
┌ Debug: Running ExpanderPipeline on types.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:39
┌ Debug: Evaluating @meta block:
│ CurrentModule = KiteUtils
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:261
┌ Debug: Evaluating @docs block:
│ Settings
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:287
┌ Debug: Evaluating @docs block:
│ MyFloat
│ SysState{P}
│ SysLog{P}
│ Logger{P, Q}
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Expanders.jl:287
┌ Warning: duplicate docs found for 'Logger{P, Q}' in `@docs` block in src/types.md:14-19
│ ```@docs
│ MyFloat
│ SysState{P}
│ SysLog{P}
│ Logger{P, Q}
│ ```
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Utilities/Utilities.jl:34
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
┌ Debug: checking for missing docstrings.
└ @ Documenter.DocChecks ~/.julia/packages/Documenter/yf96B/src/DocChecks.jl:30
┌ Warning: 1 docstring not included in the manual:
│ 
│     KiteUtils.sys_log :: Union{Tuple{Logger}, Tuple{Logger, Any}}
│ 
│ These are docstrings in the checked modules (configured with the modules keyword)
│ that are not included in @docs or @autodocs blocks.
└ @ Documenter.DocChecks ~/.julia/packages/Documenter/yf96B/src/Utilities/Utilities.jl:34
┌ Debug: checking footnote links.
└ @ Documenter.DocChecks ~/.julia/packages/Documenter/yf96B/src/DocChecks.jl:116
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
┌ Debug: Rendering functions.md [3]
└ @ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/yf96B/src/Writers/HTMLWriter.jl:766
┌ Debug: Rendering examples.md [5]
└ @ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/yf96B/src/Writers/HTMLWriter.jl:766
┌ Debug: Rendering index.md [1]
└ @ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/yf96B/src/Writers/HTMLWriter.jl:766
┌ Debug: Rendering reference_frames.md [2]
└ @ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/yf96B/src/Writers/HTMLWriter.jl:766
┌ Debug: Rendering types.md [4]
└ @ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/yf96B/src/Writers/HTMLWriter.jl:766
┌ Warning: Documenter could not auto-detect the building environment Skipping deployment.
└ @ Documenter ~/.julia/packages/Documenter/yf96B/src/deployconfig.jl:75

digital_carver · August 28, 2022, 5:54pm

Ah. The package is looking for the literal string HEAD branch:, and doesn’t seem to have been written with localization in mind. Can you try starting julia with LANG=en_US julia and run the include command there, see if that helps?

ufechner7 · August 28, 2022, 6:02pm

OK, this fixes the first warning:

ufechner@tuxedi:~/repos/KiteUtils.jl$ LANG=en_US julia --project
               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.7.3 (2022-05-06)
 _/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
|__/                   |

julia> include("docs/make.jl")
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
┌ Warning: duplicate docs found for 'Logger{P, Q}' in `@docs` block in src/types.md:14-19
│ ```@docs
│ MyFloat
│ SysState{P}
│ SysLog{P}
│ Logger{P, Q}
│ ```
└ @ Documenter.Expanders ~/.julia/packages/Documenter/yf96B/src/Utilities/Utilities.jl:34
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
┌ Warning: 1 docstring not included in the manual:
│ 
│     KiteUtils.sys_log :: Union{Tuple{Logger}, Tuple{Logger, Any}}
│ 
│ These are docstrings in the checked modules (configured with the modules keyword)
│ that are not included in @docs or @autodocs blocks.
└ @ Documenter.DocChecks ~/.julia/packages/Documenter/yf96B/src/Utilities/Utilities.jl:34
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
┌ Warning: Documenter could not auto-detect the building environment Skipping deployment.
└ @ Documenter ~/.julia/packages/Documenter/yf96B/src/deployconfig.jl:75

But still two warnings left…

digital_carver · August 28, 2022, 6:18pm

ufechner7:

│     KiteUtils.sys_log :: Union{Tuple{Logger}, Tuple{Logger, Any}}
│ 
│ These are docstrings in the checked modules (configured with the modules keyword)
│ that are not included in @docs or @autodocs blocks.

This one seems pretty self-explanatory. You have a docstring for sys_log, but haven’t included it in the manual anywhere. If you want to include it, “# Loading, saving and converting log files” section in functions.md seems like the right place for it.

ufechner7 · August 28, 2022, 6:23pm

Thank you!

But still one warning left:

ufechner@tuxedi:~/repos/KiteUtils.jl$ LANG=en_US julia --project
               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.7.3 (2022-05-06)
 _/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
|__/                   |

julia> include("docs/make.jl")
^[[A[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
┌ Warning: duplicate docs found for 'Logger{P, Q}' in `@docs` block in src/types.md:14-19
│ ```@docs
│ MyFloat
│ SysState{P}
│ SysLog{P}
│ Logger{P, Q}
│ ```

digital_carver · August 28, 2022, 7:44pm

That one is tricky, I can only guess at the reason. I think what’s going on is that @with_kw is creating several constructors, one of which is Logger(points, index ; kwargs...), and the docstring before the struct definition is seen as applying to that too. So later, when we have a separate docstring for Logger(P, steps) (which is also a two-positional-argument constructor called Logger, so has the same signature in Documenter’s eyes), it’s seen as a duplicate.

The only “solution” I can think of is to merge the later docs

ufechner7:

"""
    Logger(P, steps)

Creates a Logger object for kite power systems with `P point masses which can store up to `steps` number of time steps.
"""
function Logger(P, steps)
    logger = Logger{P, steps}()
    logger
end

at the end of the structs docstring (after $(TYPEDFIELDS)), and remove it from above the function.

ufechner7 · August 28, 2022, 8:23pm

I document now both the struct and the constructor in this way:

"""
    mutable struct Logger{P, Q}

Struct to store a simulation log. P is number of points of the tether, segments+1 and 
Q is the number of time steps that will be pre-allocated.

Constructor:
- Logger(P, steps)

Fields:

$(TYPEDFIELDS)
"""

And this is working.

Is this the suggested way to document a type and all its constructor functions?

digital_carver · August 29, 2022, 8:23am

Not normally. Normally you’d do things the way you had them, with separate docstrings. Since the different constructors will have different signatures, there will be no conflict.
Here the issue (to my understanding anyway) is that @with_kw creates many constructors, one which happens to have the same signature as your Logger(P, steps). Normally having two constructors like this would be an issue and you’d remove one of them. But here it’s being automatically generated by @with_kw and I don’t see an option to customize that in Parameters.jl

Glad to hear that!