Re: Discussion plans for today

[Ricardo Lafuente]

Hello Libor,

Thank you for your comments!

1. Yes, we'd extract comments from all the relevant files, but we're not 100% sure which files are relevant. It's probably a good moment to list what pages should appear on the user-facing website (besides the wrappers).
2. About the translation process, you are correct that the pipeline is somewhat clunky, having to maintain both the source code comments and the site markdown files. For a way out of this, we'd like to know if it is a possibility to have the "single source of truth" for documentation in the Markdown files, and not on the source itself, essentially decoupling the site content and the source code comments.

We know this might require more discussion and back-and-forth, but this might be a good way out of our Doxygen dilemma. We can take part in today's dev meeting if there's time for this discussion point?

On 7/12/21 10:29 AM, Libor Polčák wrote:

> Hello
>       Ricardo,
>       
>       
>       sorry for the late reply. My comments are inline.
>       
>       
> > Hi all,
> >         
> >         
> >         We've been twisting Doxygen in creative ways to accomodate the
> >         site needs, but got to a point where we're looking at the
> >         current situation and could use your feedback regarding how to
> >         move forward and finish things. With Doxygen, we're hitting some
> >         clear limitations:
> >         
> >         
> >           * Translation support will be hacky and difficult, since
> >         Doxygen works from code comments; gettext has no easy way to
> >         support translation of comments.
> >         
> >           * Doxygen templating is experimental and mostly undocumented.
> >         We've been running into strange bugs and coming up with even
> >         stranger workarounds
> >         
> >           * Ẁhile setting up the static blog using Pelican, we will also
> >         have to visually pretend that it's one site instead of two
> >         (Doxygen for docs and Pelican for posts). Doable but not as easy
> >         to manage and maintain.
> >         
> >         
> >         We were taking a step back to look at this and trying to
> >         understand if all the hacks are worth it.
> >         
> >       
>       
>       Sure, this seems like a perfect moment to step back.
>       
>       
> > The main reason that we have been sticking
> >         with Doxygen has been to easily extract the wrapper descriptions
> >         from the source code. So far, we haven't been using the Doxygen
> >         function reference + automatic function listing.
> >         
> >         
> >         So we would ask you about the possibility of making the main
> >         site in Pelican, with any necessary technical documentation
> >         additions handled by Doxygen whenever needed. Here's a possible
> >         plan:
> >         
> >         
> >          1. Create a script to extract the wrapper descriptions from the
> >         comments, and save them into Markdown files for Pelican.
> >         
> >       
>       
>       Just to make sure, we have also comments not only for wrappers but
>       also for other code like
>       https://www.fit.vutbr.cz/~ipolcak/jsr/doxygen/html/alea_8js.html.
>       But I guess that you mean all code, not just wrappers.
>       
>       
> >  2. These Markdown files can be easily
> >         translated using Weblate or another framework that we decide
> >         upon.
> >         
> >          3. If any special page or resource from Doxygen is needed, we
> >         can generate it separately with Doxygen and copy over the
> >         relevant files to the Pelican site output.
> >         
> >         
> >          From your side, not much changes: you can still edit the
> >         wrapper descriptions inside the source files, and they're
> >         automatically converted to Markdown files for Pelican when
> >         generating the site and blog. On the other hand, if we are not
> >         okay with the fact that there's two "single sources of truth"
> >         (description in source code + description in markdown file), we
> >         can evaluate in the meeting whether we can come up with a
> >         suitable workflow that saves time for everybody.
> >         
> >       
>       
>       AFAIU English comments are planned to be a part of the source code
>       files. English markdown files will be created automatically.
>       Translated texts will need to be written in Markdown and the
>       translation needs to be revisited after every change in the
>       English text in the comments in the code.
>       
>       
>       Do I understand correctly?
>       
>       
>       Thanks
>       
>       
>       Libor
>       
>       
>