Re: difference between readthedocs generated and local

Hi Travis,

Thanks for your reply!  This all sounds reasonable.  I won't be able to dig-in 
to this right away, but I'll put it on my list to get back to soon.

Thanks,

Ryan

On Thu, 31 Jan 2019, Travis Everett wrote:

> Ryan,
>
> I don't know a ton about how those parts of the codebase work so I stalled
> a bit hoping someone else would respond (there's some chance I'll mis-lead
> you here...). In any case, a good place to start is by seeing whether the
> behavior changed in 1.8.12/13/14. That should let you narrow your focus to
> just commits in a single version.
>
> If you aren't set up to build Doxygen from source (and/or aren't
> comfortable doing so), it's probably fine to open an issue report with the
> behavior you've seen, which version changed it, and a minimal set of
> files/config necessary to reproduce it. If you are comfortable building
> from source you can push this further and identify the specific commit.
>
> Hopefully the issue you're seeing was caused by an update to
> src/fortranscanner.i or src/fortrancode.i (there are probably only a few
> commits touching those per version). You can use git or github to identify
> which commits between two versions touched either of those files, and
> recompile/rebuild (depending on how long your docs take to build you may be
> able to speed this up a lot by making a separate config that just includes
> the minimum set of files you need to see the behavior) at each to see which
> introduces the break.
>
> If that doesn't work (or if there are more commits than I suspect touching
> those two files) you can use the more general git bisect command (along
> with a recompile and rebuild doc cycle) to narrow it down to the last-good
> commit.
>
> An issue report that identifies the commit/PR introducing the error should
> make it a quicker fix; if you're thinking of tackling the fix itself but
> need help figuring out where to start, it may help to fish around on the
> separate development list
>
> HTH,
> Travis
>
>
> On Wed, Jan 30, 2019 at 5:51 PM Ryan S. Elliott <[email protected]> wrote:
>
>> Hello,
>>
>> Thanks for the reply.
>>
>> I tried 1.8.11 on my mac and I get a Segmentation fault!
>>
>> .
>> .
>> .
>> Reading
>> /Users/relliott/unison-sync/KIM/git/kim-api/fortran/include/kim_model_compute_arguments_module.f90...
>> Parsing file
>> /Users/relliott/unison-sync/KIM/git/kim-api/fortran/include/kim_model_compute_arguments_module.f90...
>> /bin/sh: line 1: 54543 Segmentation fault: 11
>> /Users/relliott/doxygen/build/bin/doxygen
>> /Users/relliott/unison-sync/KIM/git/kim-api/build/docs/Doxyfile.docs
>>
>>
>> Anyway, then I set up a ubuntu VM and got it to work.  Indeed, 1.8.11 on
>> ubuntu
>> it seems I get the same output as RTD.  I've also confirmed that 1.8.14 on
>> ubuntu produces the same output (without the interfaces documented) that I
>> previously obtained on my mac.
>>
>>
>> So, it seems that this is a regression in behavior from 1.8.11 to 1.8.14?
>> How
>> should I go about figuring out when/where this happened and what to do
>> about
>> it?
>>
>>
>>
>> On Wed, 30 Jan 2019, Travis Everett wrote:
>>
>>> The copy on RTD indicates it was generated by doxygen 1.8.11, while the
>> one
>>> at openkim indicates 1.8.14; a good first step would be installing 1.8.11
>>> and seeing if your output matches what's on RTD.
>>>
>>> On Wed, Jan 30, 2019 at 3:08 PM Ryan S. Elliott <[email protected]>
>> wrote:
>>>
>>>> Hello,
>>>>
>>>> I'm working on the doxygen documentation for the kim-api project
>>>> (https://github.com/openkim/kim-api)
>>>>
>>>> When I locally (on my mac) generate the doxygen docs I see problems with
>>>> the
>>>> fortran docs.  In particular, there are a fair number of functions that
>>>> are not
>>>> automatically documented by the parser.  Further, no generic interfaces
>> are
>>>> documented.
>>>>
>>>> However, the exact same git commit, when used to generate the doxygen
>> docs
>>>> by
>>>> readthedocs documents all the functions and generates the generic
>> interface
>>>> docs.
>>>>
>>>> Here is a link to a readthedocs page showing the interfaces:
>>>>
>> https://kim-api.readthedocs.io/en/latest/namespacekim__model__module.html
>>>>
>>>> Here is a link to a similar page generated locally:
>>>>
>> https://openkim.org/kim-api/docs-beta.3/namespacekim__model__module.html
>>>>
>>>> In particular, also notice that in the locally generated docs the
>>>> "kim_model_is_routine_present" function is not documented!
>>>>
>>>>
>>>> I can't understand why these differences are occuring.  Can anyone point
>>>> me in
>>>> the right direction?
>>>>
>>>>
>>>> Thanks,
>>>>
>>>> Ryan Elliott
>>>>
>>>>
>>>> _______________________________________________
>>>> Doxygen-users mailing list
>>>> [email protected]
>>>> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>>>>
>>>
>>
>> --
>> Ryan S. Elliott, Ph.D. and Professor
>> Aerospace Engineering & Mechanics, University of Minnesota
>> (612) 624-2376 (626-1558 fax)
>> https://z.umn.edu/relliott
>> download vCard <https://z.umn.edu/relliott_vcf>
>> ----------
>> The distinction between past, present and future, is only an illusion, even
>>     if a stubborn one.
>>
>>                                                             Albert Einstein
>> ----------
>>
>

-- 
Ryan S. Elliott, Ph.D. and Professor
Aerospace Engineering & Mechanics, University of Minnesota
(612) 624-2376 (626-1558 fax)
https://z.umn.edu/relliott
download vCard <https://z.umn.edu/relliott_vcf>
----------
Theoretical crystallography is too difficult for crystallographers.

                                           Hans Wondratschek, June 22, 2009
----------