search

BioJulia / BioAlignments.jl

Sequence alignment tools
MIT License
60 stars 24 forks source link

Outdated documentation for SAM/BAM in BioAlignments is first hit in search #82

Closed simon-anders closed 2 years ago

simon-anders commented 2 years ago

I've just tried following the example at https://biojulia.net/BioAlignments.jl/latest/hts-files.html and got the error that BAM is not defined in BioAlignments. After some searching, I found that I have to use the package XAM instead, i.e., in the example code given, using BioAlignments should be replaced with using XAM.

How comes that the BioAlignments documentation lists the API for SAM and BAM and gives examples even though these are not part of BioAlignments? Could it be that they used to be, but you recently moved them out into their own package, XAM, but forgot to update the documentation?

If so, please take this Issue as a gentle reminder. :-)

(My problem is solved, but being new to BioJulia, I was just thoroughly confused for a bit.)

MillironX commented 2 years ago

@simon-anders The true up-to-date documentation is located at https://biojulia.net/BioAlignments.jl/dev/, and does not include any reference to SAM and BAM. Could you please share where you got your current link?

@CiaranOMara Should the latest directory be deleted from gh-pages?

simon-anders commented 2 years ago

I've googled for "julia sam alignment" and the first result was https://biojulia.net/BioAlignments.jl/latest/hts-files.html.

I guess it makes sense to have a ".../latest", but you should make sure that it really reflects the latest release. Something went wrong here because at https://biojulia.net/BioAlignments.jl/latest/, the package version is given as 2.1.0, although that version does not contain SAM/BAM any more.

Anyway, thanks for the packages; they are very useful.

kescobo commented 2 years ago

I guess it makes sense to have a ".../latest", but you should make sure that it really reflects the latest release.

This is a result of changes in the Documenter.jl package, I believe, or rather in the way it used to be configured. I believe there's a way to update the site so that any pages that do not reflect the current version have a big warning banner - perhaps we should get that set up?

Thanks for the report!

CiaranOMara commented 2 years ago

@kescobo is correct about latest being a hangover from an old configuration. @MillironX, removing latest would present a 404 error for existing links. I think we should redirect latest to stable or dev, but I'm not sure which. How do people think about latest? Is it the latest version or the latest development?

kescobo commented 2 years ago

I think latest is the latest release, so == stable

CiaranOMara commented 2 years ago

The redirect is set up so that latest points to stable.