Missing docstrings, some of which shouldn't be?

[leburgel]

I was looking at the CI log of a documentation build, and noticed a warning indicating that quite a few docstrings actually aren't included in the docs:

┌ Warning: 35 docstrings not included in the manual:
│ 
│     TensorKit.unitary!
│     TensorKitSectors.NoBraiding
│     TensorKitSectors.findindex :: Union{Tuple{I}, Tuple{SectorValues{I}, I}} where I<:Sector
│     TensorKit.insertplanarbackend :: Tuple{Any, Any}
│     TensorKit.isomorphism!
│     TensorKitSectors.Bosonic
│     TensorKit.isometry!
│     TensorKit.subblocktype
│     TensorKitSectors.GenericUnit
│     TensorKit.randisometry! :: Tuple{Type, HomSpace}
│     TensorKit.insertplanarallocator :: Tuple{Any, Any}
│     TensorKitSectors.SimpleFusion
│     Base.setindex! :: Union{Tuple{I}, Tuple{AbstractTensorMap, Any, Tuple{I, Vararg{I}}}} where I<:Sector
│     TensorKit.project_symmetric! :: Tuple{TensorMap, DenseArray}
│     TensorKit.BlockIterator
│     TensorKit.Factorizations.TruncationSpace
│     TensorKitSectors.SimpleUnit
│     TensorKit.foreachblock :: Tuple{Any, AbstractTensorMap, Vararg{AbstractTensorMap}}
│     TensorKit.repartition :: Union{Tuple{AbstractTensorMap, Int64}, Tuple{AbstractTensorMap, Int64, Int64}}
│     Base.transpose :: Union{Tuple{AbstractTensorMap}, Tuple{AbstractTensorMap, Tuple{NTuple{N₁, Int64}, NTuple{N₂, Int64}} where {N₁, N₂}}}
│     TensorKit.randisometry :: Tuple{Type, HomSpace}
│     TensorKit.randisometry :: Tuple{Tuple{Int64, Int64}}
│     TensorKitSectors.Fermionic
│     TensorKit.absorb :: Tuple{AbstractTensorMap, AbstractTensorMap}
│     TensorKitSectors.GenericFusion
│     TensorKit.TreeTransformer
│     TensorKitSectors.UniqueFusion
│     TensorKit.with_blockscheduler :: Union{Tuple{Any}, Tuple{Any, Any}}
│     TensorKit._interleave :: Tuple{Tuple{}, Tuple{}}
│     TensorKit.fusiontrees :: Tuple{HomSpace}
│     TensorKit.id!
│     TensorKitSectors.LargeZNIrrep
│     TensorKit.blockscheduler
│     TensorKitSectors.Anyonic
│     TensorKit.SubblockIterator

Some of these are probably very internal so they were intentionally left out, but there's a few that I was quite surprised about (like repartition, transpose, absorb, ...).

I guess this is a symptom of the larger issue that the library docs are currently really written very 'manually', where all docstrings are included explicitly in a deliberate order. This is nice for the clarity of the library docs which look a lot nicer than something that's automatically generated, but this also means that every time a method is added the docstring needs to be manually added. Otherwise these methods don't show up in the index and can't be found by searching, which is very inconvenient for exported methods?

Would it be worth it to have some auto-generated library docs to make sure everything is in the index, or would the loss in structure not be worth it?

[Jutho]

It is also because I started rewriting the docs, but then didn't get beyond the spaces part, so sectors, fusion trees and tensor maps still need to be handled. It was my intention to include everything (manually indeed).

[lkdvos]

I learned from Ronny that you can automatically include docstrings from specific pages, ie something like this: https://github.com/JuliaManifolds/AlgorithmsInterface.jl/blob/main/docs/src/interface.md#reference-core-interface-types--functions

One way to have both automated and manual sections could therefore be to have an index.md which includes all docstrings from certain pages, which we can still manually sort into different categories, through @autodocs.
Then, in the other parts of the docs, we can still include the relevant docstrings manually, and just have to put canonical = false.
This might give the best of both worlds?