[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Discussion plans for today

From: Libor Polčák
Subject: Re: Discussion plans for today
Date: Mon, 12 Jul 2021 11:29:20 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0 SeaMonkey/2.53.8

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 

 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?



reply via email to

[Prev in Thread] Current Thread [Next in Thread]