Share doc strings branch

[anurag-mds]

This PR implements the approach discussed in issue #547 by moving shared docstrings from exported functions into the docs directory and referencing them via @docs, eliminating duplication while preserving rendered documentation.

@iblislin Please review.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.03%. Comparing base (3291223) to head (3a2cdca).
⚠️ Report is 19 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #549      +/-   ##
==========================================
+ Coverage   85.44%   86.03%   +0.59%     
==========================================
  Files          11       13       +2     
  Lines         625      888     +263     
==========================================
+ Hits          534      764     +230     
- Misses         91      124      +33     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[iblislin]

Hi, could you rebase this PR against master?

[anurag-mds]

I can take care of the rebase, but I’m at college right now. I’ll be able to do it in ~3 hours. Just wanted to give you a heads-up so you know the timing

[iblislin]

ah, take your time :)

[anurag-mds]

Sorry for the delay, this was my first time handling rebase conflicts in this repo, so resolving them carefully took a bit longer than expected. The branch is now rebased against master.

Thanks for asking me to rebase it helped me learn how to properly resolve conflicts.

[ValentinKaisermayer]

Can you add an API section like other packages do?

# Public API
```@autodocs
Modules = [Foo]
Private = false
```

[anurag-mds]

Thanks for the suggestion Let me do this real quick!

[anurag-mds]

I have made the required modifications. Please let me know if any further refinements are needed

[iblislin]

Can you add an API section like other packages do?

# Public API
```@autodocs
Modules = [Foo]
Private = false

@ValentinKaisermayer
I built the doc, and got this warning.
Should we list the Base.* in the public API section? or it's not a common approach?

┌ Warning: 19 docstrings not included in the manual:
│ 
│     Base.hcat :: Tuple{TimeArray, TimeArray}
│     Base.hcat :: Tuple{TimeArray, TimeArray, Vararg{TimeArray}}
│     Base.:+ :: Tuple{TimeArray}
│     Base.split :: Tuple{TimeArray, Function}
│     TimeSeries.insertbyidx! :: Union{Tuple{AbstractArray, AbstractArray, Vector}, Tuple{AbstractArray, AbstractArray, Vector, Int64}}
│     TimeSeries.insertbyidx! :: Tuple{AbstractArray, AbstractArray, Vector, Vector}
│     TimeSeries._get_fname :: Tuple{Expr}
│     Base.eachcol :: Tuple{TimeArray}
│     TimeSeries.sorted_unique_merge :: Union{Tuple{IndexType}, Tuple{Type{IndexType}, Vector, Vector}} where IndexType
│     Base.:- :: Tuple{TimeArray}
│     TimeSeries._rpad :: Tuple{AbstractString, Integer}
│     TimeSeries.Candlestick
│     TimeSeries.find_ta :: Tuple{Any}
│     Base.vcat :: Tuple{Vararg{TimeArray}}
│     Base.:==
│     TimeSeries.findcol :: Tuple{AbstractTimeSeries, Symbol}
│     Base.map :: Union{Tuple{N}, Tuple{T}, Tuple{Any, TimeArray{T, N, D, A} where {D<:TimeType, A<:AbstractArray{T, N}}}} where {T, N}
│     TimeSeries._mapcol :: Tuple{Any, Any}
│     Base.eachrow :: Tuple{TimeArray}
│ 
│ These are docstrings in the checked modules (configured with the modules keyword)
│ that are not included in canonical @docs or @autodocs blocks.
└ @ Documenter ~/.julia/packages/Documenter/xvqbW/src/utilities/utilities.jl:49

[anurag-mds]

Thanks for checking.
My understanding is that methods extending Base usually aren't listed explicitly in the public API, and internal helpers(_ : prefixed)
aren't part of it either

That said, I'm happy to follow whatever convention timeseries.jl prefers
Just do let me know about it

[ValentinKaisermayer]

https://documenter.juliadocs.org/stable/man/syntax/#Info-67d1dac5cc53b84b

Documenter.jl should only consider exported symbols and those marked with public. So I wonder why we export Base.+ ?

[ValentinKaisermayer]

https://documenter.juliadocs.org/stable/man/syntax/#Info-67d1dac5cc53b84b

Documenter.jl should only consider exported symbols and those marked with public. So I wonder why we export Base.+ ?

Ah, sry got that wrong. We document it, i.e. have a docstring but they are not exported so @autodocs complains.

[ValentinKaisermayer]

DataFrames.jl simply documents everything, including, e.g. Base.hcat. Maybe this is the right approach.

https://dataframes.juliadata.org/stable/lib/functions/#Base.hcat

[anurag-mds]

I see the trade-off.
My intial assumption was to exclude base extensions and internal helpers from public API, but dataframes.jl documenting Base methods is a strong precedent.

I'm fine adopting that approach to maintain consistency.

To confirm before I proceed:
Should I include the reported Base methods in the API section while keeping internal helpers prefixed with _ excluded?

[iblislin]

I vote for including all Base.* methods in the API reference page, like DataFrames.jl does.

@anurag-mds could you try out the public keyword for Base methods?

https://documenter.juliadocs.org/stable/man/syntax/#Info-67d1dac5cc53b84b

Documenter.jl should only consider exported symbols and those marked with public. So I wonder why we export Base.+ ?

[anurag-mds]

Sounds good
I’ll mark the relevant Base.* methods as public and update the API reference accordingly.
I’ll report back if I hit any issues with Documenter

[anurag-mds]

Apologies for the delay on this update - I’m currently away from my development setup for a few days, but I’ve noted everything and will push the changes as soon as I’m back. I’ll update here if I run into any issues with Documenter.

Thanks for the guidance and patience

[anurag-mds]

@iblislin I have done all the necessary changes Kindly review it and any changes do let me know!

[anurag-mds]

Does this seems good?

[iblislin]

Thanks for your contributions!

[iblislin]

The new ref page looks fine: https://juliastats.org/TimeSeries.jl/dev/api/.
I'm going to make a new release.

[anurag-mds]

Thanks a lot for the review and for merging this!
I really appreciate the guidance throughout and learned a lot from the process. Glad the new API page looks good.

This PR helped me learn how to rebase, understand reviews, and make the necessary modifications.