Re: [Doxygen-users] Utilizing Doxygen for collaborative document building

[Petr P. <Pri...@sk...>]

If the programming language of your project is supported by Doxygen, then Doxygen is a good tool for that. The documentation closely related to code is simply written inside the sources of the code. The extra documentation is written in separate text files with the extension that does not collide with the program sources (say .doc). Then in the Doxyfile (kind of project file for Doxygen) you just include the mask(s) for the extra doc files. In my case it was like:

FILE_PATTERNS          = *.h \
                         *.cpp \
                         *.doc \
                         *.inc

If you know LaTeX, then syntax of the doc files is similar in principle. You just write plain text files with semantic markup (even though visual markup is also possible. You can even combine alternative markup. The Doxygen native markup commands was derived from Javadoc and they are summarized at http://www.doxygen.org/manual/commands.html. If you prefer, you can use Markdown syntax http://www.doxygen.org/manual/markdown.html. You can also use HTML and LaTeX fragments.

The collaboration of more people should be supported by a version control system. The text (that is non-binary) form of document sources is ideal for that kind of work.

P.


From: Molly McAllister [mailto:mol...@uc...]
Sent: Thursday, May 4, 2017 7:27 PM
To: Petr Prikryl <Pri...@sk...>
Cc: dox...@li...
Subject: Re: [Doxygen-users] Utilizing Doxygen for collaborative document building

The document will include the scientific description plus some of the technical code structure (and explanation) of a  model. At the moment it is in pdf format and needs to be updated and edited to include more overview information with graphics as well as code structure, explanation, and snippets. It needs to eventually be hosted on the web, so ultimately html format.  Would doxygen be good for this?

I work on a team and the idea was to have specialists edit their respective sections. So maybe the document would live in doxygen and multiple people could edit it some how.

The other option would be to put the code into doxygen and then document and comment around it.

On Wed, May 3, 2017 at 12:54 AM, Petr Prikryl <Pri...@sk...<mailto:Pri...@sk...>> wrote:
Basically, Doxygen transforms one set of files into another set of files. It was created namely for documenting programming-language source files. It can also be (mis)used for non-programming sources. But there may be better tools for writing just some "text documents" (for example ASCIIDOC). As far as I know, anyone can use Doxygen for free. And as Doxygen only transforms source files to target files, and the collaborators would only write the source files, they do not need to use Doxygen if they do not want. The transformation can be done by someone else. On the other hand, when writing a source file, one would like to check the result occasionally.

Can you describe what kind of "guide document" you want to build?

Doxygen does not solve the collaboration on sources by more people. The key problem of that collaboration is to keep versions and to solve collisions. For that purpose, "version control systems" were designed. And from them I would recommend to use Git (https://git-scm.com/)

Have a nice day,
Petr

-----Original Message-----
From: Molly [mailto:mol...@uc...<mailto:mol...@uc...>]
Sent: Tuesday, May 2, 2017 9:16 PM
To: dox...@li...<mailto:dox...@li...>
Subject: [Doxygen-users] Utilizing Doxygen for collaborative document building

I would like to build and edit a guide document with doxygen. I would like the document to be able to be edited by multiple members on my team. What is the best way to go about this? Does each individual need to have access to doxygen/ license?

Thanks



--
View this message in context: http://doxygen.10944.n7.nabble.com/Utilizing-Doxygen-for-collaborative-document-building-tp7854.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot _______________________________________________
Doxygen-users mailing list
Dox...@li...<mailto:Dox...@li...>
https://lists.sourceforge.net/lists/listinfo/doxygen-users



--
Molly J. McAllister
mol...@uc...<mailto:mol...@uc...>
office: (303) 497-8253<tel:%28303%29%20497-8404>