Re: [myhdl-list] Another typo in docs

[Christopher F. <chr...@gm...>]

On 1/6/2015 2:31 PM, Ben wrote:
<snip>
>>>
>>> Further to this, I've got a working doctest suite for rtl.rst. This is at:
>>>
>>> https://bitbucket.org/heng/myhdl/branch/0.9-dev
>>>
>>> I had to replicate some code in the documentation for doctest to work
>>> (which just makes it easier to copy and paste, though potentially open
>>> to replication errors down the line). The issue seemed to be related to
>>> globals in the doctest string, though I've not tried to hard to get to
>>> the bottom of it.
>>>
>>
>> I did not find a work around for this.  Your approach is nice
>> to enable doctest but I am worried the maintenance will be a
>> pain (double code snips).
>
> Maybe there is a way using the ``doctest_global_setup`` config value
> [0]. The conf.py file is python so it should be possible to read (part
> of) another python file to populate that variable. That code would be
> automatically 'duplicated' on top of each file ...
>
> Just my 2c.
>
> Ben.

I think there are a couple different approaches to
workaround the issue.  But I don't know if it helps
achieve the overall goal of doctest, which is (in
my mind):

    1. verify the code snips are correct in the
       documentation with automated and regression
       testings

I think for this to be useful it really needs to test
the code that is eventually displayed.

This means that the doctest in the sphinx documentation
might not be possible depending if the issue can be
resolved.  Because there are multiple systems etc. not
sure where/how to start debugging the issue.

If more regression tests are desired it would be easier
to create more tests than try and enable tests embedded
in the documentation.

Regards,
Chris