Change source links in model docs to local paths (Trac #1263)

[smk78]

[See PR SasView/sasmodels#103]

In addressing http://trac.sasview.org/ticket/883, http://trac.sasview.org/ticket/1187, and #1266 hyperlinks to the MASTER model source code files on !GitHub were added to the model documentation files.

Subsequent discussions at Code Camp IX suggested it might be more useful to replace these hyperlinks with the paths to the local copies of the model source code files on a Users machine (so that they see the code for the version of !SasView they have installed).

This might, for example, be possible to do at the point the docs are built, but would require some furtling of the build script to ensure the paths were correct for different operating systems.

Migrated from http://trac.sasview.org/ticket/1263

{
    "status": "new",
    "changetime": "2019-03-30T06:00:30",
    "_ts": "2019-03-30 06:00:30.375186+00:00",
    "description": "In addressing #883, #1187, and #1240 hyperlinks to the MASTER model source code files on !GitHub were added to the model documentation files.\n\nSubsequent discussions at Code Camp IX suggested it might be more useful to replace these hyperlinks with the paths to the local copies of the model source code files on a Users machine (so that they see the code for the version of !SasView they have installed).\n\nThis might, for example, be possible to do at the point the docs are built, but would require some furtling of the build script to ensure the paths were correct for different operating systems.",
    "reporter": "smk78",
    "cc": "",
    "resolution": "",
    "workpackage": "SasView Documentation",
    "time": "2019-03-27T16:36:20",
    "component": "SasView",
    "summary": "Change source links in model docs to local paths",
    "priority": "blocker",
    "keywords": "",
    "milestone": "SasView 4.3.0",
    "owner": "",
    "type": "enhancement"
}

[pkienzle]

Trac update at 2019/03/28 23:42:10: pkienzle commented:

Easy enough to automate the linkage to source from the model docs by tweaking sasmodels/doc/genmodel.py.

• Link to "https://github.com/SasView/sasmodels/blob/v%s/sasmodels/models/%s"%(sasmodels.__version__, filename)
• Use filename from model_info.filename (for the .py file) and model_info.sources (for all the C dependencies).
• Code goes in gen_docs() function

Putting it together:

source_header = """
Source
------

"""
source_url = "https://github.com/SasView/sasmodels/blob/v%s/sasmodels/models"%sasmodels.__version__
source_links = ["`%s <%s/%s>`_"%(filename, source_url, filename)
                for filename in [os.path.basename(model_info.filename)] + model_info.sources]
docstr3 = source_header + "\n".join(source_links)

[smk78]

Trac update at 2019/03/29 14:47:52: smk78 commented:

@pkienzle notes:

> Adding source code links to github/blob/master into the various models is not advisable.
> 
> A couple of reasons:
> 
> (1) this is the latest source code, not necessarily the source associated with that 
>     version of the file.
>
> (2) the github blob/master reference may change (I think it has already done so once or 
>     twice).
>
> (3) keeping the links updated by hand is tedious.
> 
> Twiddling the code in doc/genmodel.py so that it automatically links to the python file 
> for the model, as well as any source dependencies listed in model_info.sources, fixes 
> (1) and (3) but maybe not (2) if !GitHub changes its tree layout at some point in the 
> future...

[smk78]

Trac update at 2019/03/29 15:06:07:

• smk78 commented:

Making this a blocker for 4.3.0 but should try and fix sooner if possible.

• smk78 changed milestone from "SasView Next Release +1" to "SasView 4.3.0"
• smk78 changed priority from "major" to "blocker"

[sasview-bot]

Trac update at 2019/03/30 06:00:30: Paul Kienzle <[email protected] commented:

In changeset c1e44e5b1121db2a5c034ed4dfd86dac0f666034:

#!CommitTicketReference repository="sasmodels" revision="c1e44e5b1121db2a5c034ed4dfd86dac0f666034"
Add local link to source files.  Refs #1285.