Ticket #9599 (closed: fixed)

Opened 6 years ago

Last modified 5 years ago

Depricated Algorithm links in Sphinx

Reported by: Owen Arnold Owned by: Martyn Gigg
Priority: major Milestone: Release 3.2
Component: Documentation Keywords:
Cc: Blocked By:
Blocking: Tester: Jay Rainey

Description

The links to the 'Use Instead' algorithms aren't working out properly in the algorithm html pages generated by Sphinx. See DiffractionFocusing.

  • Possibly have an additional argument on useAlgorithm() to specify the version of the algorithm to use.
  • Default to the latest version of the current algorithm
  • Allow the useAlgorithm to specify a completely different algorithm and have the links to that documentation properly generated.

Set against release 3.2, but completely understand if this gets moved to later.

Change History

comment:1 Changed 6 years ago by Nick Draper

  • Status changed from new to assigned

comment:2 Changed 6 years ago by Martyn Gigg

  • Status changed from assigned to inprogress

comment:3 Changed 6 years ago by Martyn Gigg

Standardize the version part of the deprecation message.

Refs #9599

Changeset: e040a2741eeaff4b23838138c70a5a0ed5416f26

comment:4 Changed 6 years ago by Martyn Gigg

Update algorithm deprecation warnings in docs

Using the new standardized format we can properly link to the correct version of the algorithm that replaces the deprecated one. Refs #9599

Changeset: d8a6dcdd7aa52f88cb3a65f6f316658394a38d3a

comment:5 Changed 6 years ago by Martyn Gigg

Only warn on replacement algm being invalid, rather than throwing.

We shouldn't stop the algorithm execution because of it. Refs #9599

Changeset: 30288ed4a57b3b91cde07ee78cc5526c1dce7f3e

comment:6 Changed 6 years ago by Martyn Gigg

Fix useAlgorithm messages for a few DataHandling algorithms.

Refs #9599

Changeset: 184c411959053c9475990b8e828007f455f7780c

comment:7 Changed 6 years ago by Martyn Gigg

Branch: feature/9599_standardize_alg_deprecation_msg

Tester: Build the html documentation using the docs-html target. Look at the Rebin page (build/docs/html/algorithms/Rebin.html) and check that there is no deprecation message as expected. Now find some deprecated algorithms:

  • DiffractionFocussing-v1
  • FindUBUsingMinMaxD
  • StitchMD

and verify that for the algorithms that suggest using another algorithm, you can click the link to get to that algorithm.

comment:8 Changed 6 years ago by Martyn Gigg

Fix doxygen warnings in DeprecatedAlgorithm

Refs #9599

Changeset: 54f29df96b77d1666a5cbce95323aee96521dee2

comment:9 Changed 6 years ago by Martyn Gigg

  • Status changed from inprogress to verify
  • Resolution set to fixed

comment:10 Changed 6 years ago by Peter Peterson

  • Status changed from verify to verifying
  • Tester set to Peter Peterson

comment:11 Changed 6 years ago by Peter Peterson

  • Status changed from verifying to reopened
  • Resolution fixed deleted

Merging this into master breaks the category links at the bottom of the algorithm pages. Also, it isn't rendering DiffractionFocussing-v1 with the link. Please merge master into this branch and re-close the ticket.

comment:12 Changed 6 years ago by Martyn Gigg

  • Status changed from reopened to inprogress

comment:13 Changed 6 years ago by Martyn Gigg

  • Status changed from inprogress to verify
  • Resolution set to fixed

I've merged master in. I cleaned out my built documentation tree and when I rebuilt everything I get the working links for both the deprecation and categories.

Sphinx has a habit of trying to clever and cache things so that it doesn't always rebuild. Could you try cleaning out the built stuff and then rebuilding:

rm -fr docs/doctrees
rm -fr docs/html
ninja docs-html

comment:14 Changed 6 years ago by Jay Rainey

  • Status changed from verify to verifying
  • Tester changed from Peter Peterson to Jay Rainey

comment:15 Changed 6 years ago by Jay Rainey

Older (deprecated) algorithms now link to their latest version correctly. Code changes are sensible & address the issue. The issue Peter noted in comment:11 no longer exists.

I did notice one style issue. The warning div expands across and behind the image, which isn't ideal. Instead, I will make a change in this branch to hide the overflow, which will make it look better (e.g. it will expand until it hits another div).

comment:16 Changed 6 years ago by Jay Rainey

Prevent warning message being hidden behind image. Refs #9599.

Changeset: 995365cf2872e0a43c2f1798edc53dc83be6a0dd

comment:17 Changed 6 years ago by Jay Rainey

  • Status changed from verifying to closed

comment:18 Changed 6 years ago by Jay Rainey

Merge remote-tracking branch 'origin/feature/9599_standardize_alg_deprecation_msg'

Full changeset: c7eac2f307145f7603f8d83191ee534ee576b445

comment:19 Changed 5 years ago by Stuart Campbell

This ticket has been transferred to github issue 10442

Note: See TracTickets for help on using tickets.