Package: doxyth
DoxyTHDoxyTH stands for Doxygen inline-documentation Translation Helper. This small package aims to provide a
quick way to generate Doxygen docs in HTML (LaTeX will come later) in different languages easily.Nota Bene:Below, "a/the Doxyfile" refers to the Doxygen configuration file, however it might be named. However,Doxyfile(in code) refers to the exact name of the file.Pre-requisitesAs DoxyTH is a support forDoxygen, you must have it installed. You can download it onthis page.Furthermore, Doxygen must be in yourPATH. If it is not, or if you doubt it is, check how to do it for your system.
A simple search of<OS> put variable in path(OS being your Operating System) may be enough to find
what you are looking for.You must have Python 3.6 or better, else you won't be able to install it through pip.You should also know how to customise aDoxyfile(Doxygen configuration file).SetupInstallationYou first have to install the package.
You can install it automatically via pippip install doxythYou can also install it by cloning the Github repository (deprecated)Setting up the translations folderIn your project directory, create a directory that will contain all the translations.
You can name it however you want, even though a meaningful name liketranslationsis still better.Inside, you have to create a directory with theISO 639-1 2-letters codefor the desired language. Directories having more or less than 2 charaters will be ignored by DoxyTH, but unrecognised
2-characters directories will generate warnings.This is an example layout (and the one I use for the DoxyTH package documentation!)<path>\DOXYTH\TRANSLATIONS
|--- en/
|       doxyth.dthdoc
|       gendoc.dthdoc
|
|--- fr/
        gendoc.dthdoc(I simplified the tree for more readability)In each language directory, you will need to create one (or more).dthdocfiles. All files having
another extension will be ignored.Layout of a .dthdoc fileEach file follows the current format:&doc_id <ID>
"""
<DOCUMENTATION>
"""IDis the ID you will put in your code, andDOCUMENTATION(everything between the two""") is what will replace
the doclines where this ID is found.WARNING: Be aware that the line breaks are important. The"""must be ALONE on their line.DoxyTH will remove any empty lines between the start of the doclines and the start of your comment
(same as between the end of your comment and the end of the doclines) to avoid problems when passing the file lines to a
postprocess.Layout of the language selection fileYou can create two files that will alter the output of the language selection html file.One is called_TEMPLATE.htmland must contain the main template.The other is called_SNIPPET.htmland must contain the language snippet that will be used for each language._TEMPLATE.htmlThis file contains the full template of the html file.
Create it however you want, using variables to put things dynamically in the template.Mandatory variables:$langs: The group of snippets created and filled with variables.Optional variables:$doxythversion: The current version of DoxyTH$projectname: The name of the project (PROJECT_NAMEin the Doxyfile)$projectnumber: The version of the project (PROJECT_NUMBERin the Doxyfile)$projectbrief: The brief description of the project (PROJECT_BRIEFin the Doxyfile)Example:<!DOCTYPE html><htmllang="en"><head><metacharset="UTF-8"><metaname="generator"content="DoxyTH $doxythversion"><title>$projectname: Language selection</title><style>...</style></head><body><divid="projectname">$projectname<spanid="projectnumber">$projectnumber</span></div><divid="projectbrief">$projectbrief</div><hr><h2>Language selection</h2><divid="lang-container">$langs</div></body></html>_SNIPPET.htmlThis file contains the snippet that will be used for each language.Mandatory variables:$lang: The language codeExample:<ahref="./$lang/index.html"><divclass="lang">$lang</div></a>In-code documentationIn your code, you can then start to write thedoc_ids.
If you wish to replace doclines by a translations, put adoc_idfollowing this layout:"""### &doc_id <PREFIX>:<ID>"""(For advanced users, the regex pattern isr"\s*###\s*&doc_id\s*")WARNING: Don't forget the prefix! The prefix is the name of the documentation file
thedoc_idwas found in.Example: If you have a file namedmydocs.dthdocwhich contains amy_doc_idID inside,
The fulldoc_idyou need to include in your code ismydocs:my_doc_id.See below under Usage how to deactivate file prefixes, if you wish to do so.Running the programUsageThis is the usage provided by argparse itself:usage: __main__.py [-h] [--verify] [-V] [--noverbose] [-F] [-D DOXYFILE] [-O OUTPUT]
                   [-P POSTPROCESS] [--listpostprocesses] [--debug | --mute]
                   [--nocleanup] [--skipgen]
                   translation_dirPositional argumentstranslation_dir: The translations folder explained above.Optional arguments-h: prints this usage message--verify: verifies the layout of the translations folder and all files inside, instead of actually generating the
documentation-V(or--version): prints the version then exits.--noverbose: no output will be printed in the console.-F(or--nofileprefix): Deactivates the file prefixes when registeringdoc_ids.-D(or--doxyfile): Path to a custom Doxyfile. If this option is not provided, DoxyTH will look for a file
namedDoxyfileby default. Passing this option is necessary only when your Doxygen configuration file is
NOT namedDoxyfile-O(or--output): Path to the output directory. If not given, defaults todocs/.-P(or--postprocess): Passes the file lines to a postprocess instead of printing them back to Doxygen.--listpostprocesses: Lists all the available postprocesses, then exits.[--debug|--mute]:debugprints everything, including non-error from the Doxygen output, whereasmutetotally
mutes Doxygen, including the warnings and errors (and also those of DoxyTH itself). Both are NOT recommended unless
you perfectly know what you are doing.--nocleanup: Leaves the temporary files upon finishing generating the documentation. You shouldn't be using this
option unless you know why you use it.--skipgen: Debug option. Skips the Doxygen docs generation. DO NOT use unless you know how to.Generating documentationIf you want to generate the documentation from the different translations files, simply run the gendoc packagepython -m doxyth.gendocorpython -m doxythusing the usage above.OutputThe result will be in the output directory you gave, and if you gave none, indocs/.The output directory will contain a subdirectory with the language code of said language, and inside will be a full
Doxygen generation. Doxygen's output language will be set to said language, if a translation exists.You will also find a index.html in the output directory. This file is created by DoxyTH, following a template html file.
If you wish to customise it, seeVerifying the translationsIf you wish to verify the translations files/directories, you can do so by running the verify packagepython -m doxyth.verifyIts usage is as follows:usage: verify.py [-h]
                 {directory,dir,d,languagedirectory,langdir,ld,file,f} documentation

positional arguments:
  {directory,dir,d,languagedirectory,langdir,ld,file,f}
                        Sub-modules
    directory (dir, d)  Verify the documentation format of the whole
                        translations directory
    languagedirectory   Verify the documentation format of a language
        (langdir, ld)   directory
    file (f)            Verify the documentation format of a file

                        Positional arguments
    documentation       The path of either the directory or the fileIf you choose to verify the whole directory, it will ouput the number of translations per language and print a warning
if the number of translations of at least one language is different from the others.If you choose to verify either a language directory or a file, it will print the number of doc_ids found in this file,
or any errors if some are found.Troubleshoot"It doesn't work!". Yes, that happens, I'm sadly no master in my craft yet and you can sometimes get some unexpected
errors. First thing to do, re-run the program with the--debugoption, so you can have the full output, Doxygen output
included.I will do my best to list the errors you may encounter, and how to fix them. If you have any question, or the fix does
not work, please create and issue, describe it the best possible, and file the full output (including the command
itself) so I can work on it better and faster.Exception: Unexpected EOF while reading.The traceback of this exception will often look like this:Traceback (most recent call last):
  File "C:\Users\MOI\AppData\Local\Programs\Python\Python36-32\lib\runpy.py", li
ne 193, in _run_module_as_main
    "__main__", mod_spec)
  File "C:\Users\MOI\AppData\Local\Programs\Python\Python36-32\lib\runpy.py", li
ne 85, in _run_code
    exec(code, run_globals)
  File "C:\Users\MOI\AppData\Local\Programs\Python\Python36-32\lib\site-packages
\doxyth\doxyth.py", line 185, in <module>
    DoxyTH()
  File "C:\Users\MOI\AppData\Local\Programs\Python\Python36-32\lib\site-packages
\doxyth\doxyth.py", line 38, in __init__
    self.__flow(args)
  File "C:\Users\MOI\AppData\Local\Programs\Python\Python36-32\lib\site-packages
\doxyth\doxyth.py", line 61, in __flow
    lines = self.__modify_lines()
  File "C:\Users\MOI\AppData\Local\Programs\Python\Python36-32\lib\site-packages
\doxyth\doxyth.py", line 166, in __modify_lines
    raise Exception(f"Unexpected EOF while reading.")Explanation: The program found an unexpected EOF (End Of File) while reading it.POTENTIAL CAUSES:You did not close a documentation in one of the translations files (.dthdoc files).You did not close a doclines in one of your files.SOLUTIONS:Look into the file that was last read before the exception was raised. (Activating the--debugoption is useful
for that). The last line before the traceback will look likeReading C:/my_folder/my_file.py...which allows you to
locate the file easily.Check if the opening and closing tags (""") of the doclines are ALONE on their line (only stripped characters, like
tabs, spaces and newlines are allowed on this line).IndexError: list index out of rangeIt often looks like this:Traceback (most recent call last):
  File "C:\Users\MOI\AppData\Local\Programs\Python\Python36-32\lib\runpy.py", li
ne 193, in _run_module_as_main
    "__main__", mod_spec)
  File "C:\Users\MOI\AppData\Local\Programs\Python\Python36-32\lib\runpy.py", li
ne 85, in _run_code
    exec(code, run_globals)
  File "C:\Users\MOI\AppData\Local\Programs\Python\Python36-32\lib\site-packages
\doxyth\__main__.py", line 3, in <module>
    Gendoc()
  File "C:\Users\MOI\AppData\Local\Programs\Python\Python36-32\lib\site-packages
\doxyth\gendoc.py", line 85, in __init__
    self.flow(args)
  File "C:\Users\MOI\AppData\Local\Programs\Python\Python36-32\lib\site-packages
\doxyth\gendoc.py", line 195, in flow
    **self.retrieve_replacements_from_doxyfile()
  File "C:\Users\MOI\AppData\Local\Programs\Python\Python36-32\lib\site-packages
\doxyth\gendoc.py", line 221, in retrieve_replacements_from_doxyfile
    final['projectbrief'] = re.split(r'^PROJECT_BRIEF\s*=\s*["\'](.+)["\']', lin
e.strip())[-2]Explanation: The list is not long enough to get the before-the-last element.POTENTIAL CAUSES:This exception can be caused by a few things (everything managed by regexes, actually).
If the last line before the traceback isCreating language selection file, then it might be because of how you
formatted your doxyfile.SOLUTIONS:If the last line before the traceback isCreating language selection file, then check the Doxyfile and look at thePROJECT_NAMEandPROJECT_BRIEFvariables. The text you put in value must always be between quotes, may they be
simple (') or double (").The "silent" problemsSometimes, there is a problem, even if the program ran successfully and no exception was thrown."Some of the characters that are in my code don't appear!": It may be because either the program or your computer
decided to use an encoding that doesn't support those characters. I created a safe mode that encodes the text into ascii
to avoid any further error with the text. So instead of crashing, it deletes said characters and continues.It's not the best, but it avoids not being able to create the documentation of a WHOLE file.