Utilizing Doxygen for collaborative document building

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Utilizing Doxygen for collaborative document building

Molly
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
Reply | Threaded
Open this post in threaded view
|

Re: Utilizing Doxygen for collaborative document building

Petr Prikryl
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:[hidden email]]
Sent: Tuesday, May 2, 2017 9:16 PM
To: [hidden email]
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|

Re: Utilizing Doxygen for collaborative document building

Molly
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 <[hidden email]> 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:[hidden email]]
Sent: Tuesday, May 2, 2017 9:16 PM
To: [hidden email]
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users



--
Molly J. McAllister
[hidden email]
office: <a href="tel:%28303%29%20497-8404" value="+13034978404" target="_blank">(303) 497-8253

<a href="tel:%28831%29%20261-5149" value="+18312615149" target="_blank">

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|

Re: Utilizing Doxygen for collaborative document building

Mark

On May 5, 2017, at 2:26, Molly McAllister <[hidden email]> wrote:

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.

I think you’d be better off using Asciidoctor (Asciidoc superset that is actively supported) for this plus the aforementioned git, or other versioning system. You can put code (you do mean source code?) fragments into Asciidoctor and have them syntax highlighted in the output.

Doxygen is for when you want your readers to be able to explore the code structure or get reference information about use of an API.

Regards

   -Mark

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|

Re: Utilizing Doxygen for collaborative document building

Petr Prikryl
In reply to this post by Molly

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:[hidden email]]
Sent: Thursday, May 4, 2017 7:27 PM
To: Petr Prikryl <[hidden email]>
Cc: [hidden email]
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 <[hidden email]> 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:[hidden email]]
Sent: Tuesday, May 2, 2017 9:16 PM
To: [hidden email]
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users




--

Molly J. McAllister

[hidden email]
office: <a href="tel:%28303%29%20497-8404" target="_blank">(303) 497-8253




------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users