JuliaDocs/Documenter.jl

Easier doctests of non-exported functions

Open

#2,126 opened on May 21, 2023

View on GitHub
 (9 comments) (0 reactions) (0 assignees)Julia (910 stars) (513 forks)batch import
Topic: UsabilityType: Enhancementhelp wanted

Description

Hello,

I've recently started adding more doctests to unexported functions in my code, and I seem to be repeating the same boilerplate-y setup quite a bit, e.g.

"""
    parsechecksum(checksum::String)
    
...text...

```jldoctest; setup = :(import DataToolkitCommon.Store.parsechecksum)
julia> parsechecksum("crc32c:9c0188ee")
(:crc32c, 0x9c0188ee)
```
"""

Is there some way this boilerplate could be avoided?

Contributor guide

Tech stack
None
Domain
documentationtesting
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Julia programmingDocumenter.jl basicsDoctest setup mechanics
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
Explore the codebase for how doctests are processed, likely in src/DocHelpers.jl or src/doctests.jl. Consider adding a keyword argument or configuration to allow automatic import of the module's functions. Review comments in the issue for potential approaches discussed.