patchGNU Octave - Patches: patch #8666, doc: adjusting octave examples...

 
 

patch #8666: doc: adjusting octave examples test to exactly match output

Submitter:  CarnĂ« Draug <carandraug>
Submitted:  Sun 03 May 2015 02:39:18 AM UTC
   
 
Category:  Core : other Priority:  1 - Later
Status:  Wont Do Privacy:  Public
Assigned to:  None Open/Closed:  Closed
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Mon 30 Aug 2021 08:13:01 AM UTC, comment #7: 

Regarding comment #6: Thanks for the explanation of the patches.  And sorry for the way too long time they were ignored.

Both attached patches file #33993 and file #33884 no longer apply cleanly to the default branch (no big surprise after 6 years đŸ˜“).  The refactoring burden of the patches is high.

Summarizing: the patches in their current shape are of little value compared to starting from scratch again.

Another feasible approach would be improving the docstring package to cope with existing documentation, rather than adapting the whole Octave core documentation for the need of a package.

Closing this item.  If someone updates the patches for the latest Octave development branch it can be reopened again.

Kai Torben Ohlhus <siko1056>
Group Member
Fri 27 Aug 2021 06:31:22 PM UTC, comment #6: 


> What is the final goal of this patch?


The goal of this patch is twofold:

1) ensure that the examples in the documentation are valid (if a function changes behaviour but someone forgets to update the documentation accordingly, the doctest package will be able to catch it)

2) increase the available tests (because code examples now become tests as well).

> I think it is more useful to add the examples as BIST into that function as well.


Sure, more BISTS are fine. But we don't want to remove examples from the documentation. This approach, use the doctest package, is better in that you don't need to duplicate them. An example code automatically becomes a BIST.

Carnë Draug <carandraug>
Group Member
Fri 27 Aug 2021 06:14:09 PM UTC, comment #5: 

no request to Kai's Need Info in over a year.  maybe just close this until it in raised as an issue again in the future.

Nicholas Jankowski <nrjank>
Group Member
Sat 18 Jan 2020 11:18:12 AM UTC, comment #4: 

Review for Octave 6.

The attached patches mainly reformat Octave texinfo docstrings.

What is the final goal of this patch?  Should OF doctest

https://octave.sourceforge.io/doctest/index.html

be able to test this functions of core Octave?  I think it is more useful to add the examples as BIST into that function as well.

In Octave we also hardly use @verbatim inside texinfo docstrings and this converts many @example to those.  Is this required for OF doctest?

Does anyone still work on this approach otherwise we should close this item.

Kai Torben Ohlhus <siko1056>
Group Member
Wed 06 Jul 2016 04:26:57 PM UTC, comment #3: 

No particular action needed here for 4.2.0.

> a tst file will be extracted from the documentation


I don't think that will be necessary.  octave-doctest does all that already.

However, I should update this patch: the dev version of doctest will skip the non-semantic examples-as-math-or-diagrams.

Colin Macdonald <cbm>
Wed 06 Jul 2016 02:05:54 PM UTC, comment #2: 

Is the plan that a  tst  file will be extracted from the documentation?  If so, I take it that no patch has been written to do that, and so this item can be ignored for the 4.2.0 release.  Is that right?

Lachlan Andrew <lachlan>
Tue 12 May 2015 10:27:01 PM UTC, comment #1: 

I've attached another patch for doctests.

One thing that's clear is @example gets used as an alternative to tex.  This is not semantically correct.

I've replaced with @verbatim which sounds about right.  But it doesn't indent like @example does.  Here I've just moved them in manually roughly the same number of spaces, which doesn't feel right.

What is the right thing to do?  New @ environment?  New formatting for @verbatim to match the @example intend?

(file #33993)

Colin Macdonald <cbm>
Sun 03 May 2015 02:39:18 AM UTC, original submission:  

Putting the patch from the mailing list here otherwise it will be forgotten

https://lists.gnu.org/archive/html/octave-maintainers/2015-03/msg00387.html

Basically, the idea is to use the examples in help text as more tests. This will also prevent our documentation from become out of date with the actual code.

Carnë Draug <carandraug>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #33993:  linear_alg_doctests.diff added by cbm (5KiB - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by nrjank (Posted a comment)
  • -email is unavailable- added by siko1056 (Posted a comment)
  • -email is unavailable- added by lachlan (Posted a comment)
  • -email is unavailable- added by cbm (Updated the item)
  • -email is unavailable- added by carandraug (Submitted the item)
  • -email is unavailable- added by carandraug (author of the patch)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 9 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-08-30 siko1056 StatusNeed Info Wont Do
        Open/ClosedOpen Closed
    2020-01-18 siko1056 CategoryNone Core : other
        Priority5 - Normal 1 - Later
        StatusNone Need Info
        Summaryadjusting octave examples test to exactly match output doc: adjusting octave examples test to exactly match output
    2015-05-12 cbm Attached File- Added linear_alg_doctests.diff, #33993
    2015-05-03 carandraug Attached File- Added svd_plus_misc_doctest.diff, #33884
        Carbon-Copy- Added -email is unavailable-

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code