Opened 5 years ago

Last modified 5 years ago

#1263 new enhancement

Change source links in model docs to local paths

Reported by: smk78 Owned by:
Priority: blocker Milestone: SasView 4.3.0
Component: SasView Keywords:
Cc: Work Package: SasView Documentation

Description

In addressing #883, #1187, and #1240 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.

Change History (5)

comment:1 Changed 5 years ago by pkienzle

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)

comment:2 Changed 5 years ago by smk78

@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...

comment:3 Changed 5 years ago by smk78

  • Milestone changed from SasView Next Release +1 to SasView 4.3.0
  • Priority changed from major to blocker

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

comment:4 Changed 5 years ago by Paul Kienzle <pkienzle@…

In c1e44e5b1121db2a5c034ed4dfd86dac0f666034/sasmodels:

Add local link to source files. Refs #1263.

comment:5 Changed 5 years ago by GitHub <noreply@…>

In f64b154aac06f600d5b287dc1153a9383f0428e8/sasmodels:

Merge pull request #103 from SasView?/ticket-1263-source-link

Add local link to source files. Refs #1263.

Note: See TracTickets for help on using tickets.