#DocUpdate: Discuss with Eduardo and figure out if there is a way to grab latest release version name-number in documentation

[shaloo]

This ticket is based on discussion with Rola and Hector on Aug 16, 2019.
At present, all pipeline descriptions have textual release number (3.1.4). Discuss with Eduardo (seek Hector's help to get in touch with him), and figure out if we can automate this.

Here are my initial thoughts:

• I know how to use a variable and publish RTD docs that display value of that variable. Say this is GenPipes Release version number var - "$RelNum".
• In GenPipes artifactory or repositories, is there a file that contains the latest release number that is stable and usable for new users? If there is a file, I need to know its name and location in repository. I can use that as the gold-standard and populate $RelNum in Sphinx/RTD documentation. This will ensure that when the version updates, the latest number shows in all documentation.
• Caveat: If there is a difference in GenPipes algorithms across versions, the new users may get confused if the displayed version number is latest but documentation corresponds to older algorithm description. We need to streamline process that ensures documentation is updated in sync with the release number update (automatic).

[pphector]

Hello Shaloo,
I am adding Édouard to this conversation so that maybe he can help us out. Your solution is probably the best approach. By using the variable (e.g. $RelNum) we can ensure that all the docs have the same version displayed at once. I don't think there is any real discrepancy between algorithms across versions that would cause concern. The main issue is finding a file that is stable and that contains the latest release version (because the VERSION file in the toplevel directory has the latest beta version).

But discussing with Edouard, we wanted to point out two things that could be done:

• Use the VERSION but explore the possibility of updating only from the latest stable release. This would also have the added advantage that if we are parsing things from other files, we can maybe just standardize the release we are parsing from, so that everything is parsed from the same release and therefore there are no contradictions.
• The other option that was proposed was to look at the "downloads" folder and just parse the latest release version from there... if there is any way to do that: https://bitbucket.org/mugqic/genpipes/downloads/

Any thoughts?

[ehenrion]

Regarding the use of the URL, the version of GenPipes can also be found using the tags : https://bitbucket.org/mugqic/genpipes/downloads/?tab=tags

Hope that could help !

[shaloo]

Thanks @ehenrion, this helps.

I am able to use a variable that gets replaced at doc build time for RTD with version info read from a file as long as the replacement content is in a .rst file (restructured text). As of now, there seems to be no way to use the same approach for a markdown file. Current readme.md are all markdown files and those have hardcoded version info. If we choose to keep all Pipeline reference user guides in md format, i may have to hardcode version :-(. Will discuss with Rola and Hector in next sync up for GSoD to figure a way out.

[shaloo]

For now, all the Pipeline references in RTD are .rst content files. Only RNS SEq light pipeline is saved as md file to prove that Sphinx/RTD can ingest content from .rst as well as .md If we choose the latter (markdown) then variable based content replacement is not supported.

[shaloo]

Solved for all .rst based files - they now refer to Version info from the link Eduardo shared. Only md file format cannot have a way to insert it at build time for now. That will be addressed by #38 - if we choose to keep files in .md Otherwise for rst we are pretty much done - resolved.