Documenter.jl: Missing Docstring (random?)

lmiq · July 14, 2023, 12:36pm

In this package, I reference some doc strings, as usual with @docs macro.

Locally, using the LiveServer.servedocs(), some docstrings do not show up, but some of these show up when the documentation is actually deployed.

Specifically, this doc string:

github.com

m3g/ProteinSecondaryStructures.jl/blob/c1daf1bdff20ef296e6dfa35326b1f2dd008364c/docs/src/explanation.md?plain=1#L48


      
          
          See the [DSSP secondary structure classification](https://pdb-redo.eu/dssp/about) for further information.
          
          The `code number` are used here to output the matrices of secondary structures obtained
          from trajectory runs. 
          
          ## Data structure
          
          The output of the secondary structure calculations is a vector of `SSData` elements, with the following data, for each residue:
          
          ```@docs
          SSData
          ```
          
          The output of `stride_run` or `dssp_run` is a vector of `SSData` structures, one for each residue. For example: 
          
          ```julia-repl
          julia> using ProteinSecondaryStructures
          
          # Replace the next assignment with a custom PDB file name
          julia> pdbfile = ProteinSecondaryStructures.Testing.examples[1].filename

shows correctly in the deployed docs:

https://m3g.github.io/ProteinSecondaryStructures.jl/stable/explanation/#Data-structure

But the same doc string, in a different page:

github.com

m3g/ProteinSecondaryStructures.jl/blob/c1daf1bdff20ef296e6dfa35326b1f2dd008364c/docs/src/reference.md?plain=1#L5


      
          # Reference
          
          ## Basic data structure
          
          ```@docs
          SSData
          ```
          
          ## Single-PDB runs
          
          ```@docs
          stride_run
          dssp_run
          ```

Does not show up:

https://m3g.github.io/ProteinSecondaryStructures.jl/stable/reference/#Basic-data-structure

What may be going on? Any insight?

ericphanson · July 15, 2023, 11:34am

I think Documenter only shows docstrings once. In Syntax · Documenter.jl it says it should error though if there are repeats.

lmiq · July 15, 2023, 11:44am

Uhm, but actually I was getting the error before the duplicate (and not only with that function). I thought that the example with the duplicate would help, but seems I introduced another variable.

ericphanson · July 15, 2023, 11:51am

Ah ok, in that case I’m not sure. I’ve been confused before by docstrings not showing up because they were inadvertent duplicates, so that’s the first thing I’d check for. Otherwise no idea. Maybe some kind of revise/file watching issue with LiveServer? In which case restarting the Julia session could help.

lmiq · July 16, 2023, 6:41pm

Indeed, removing the duplicate @docs call to that entry solves the deployed version. I get errors locally with that and other functions, when using LiveServer. I’ll try to figure out what’s going on, but it is less relevant now that the issue does not appear in the published docs.