I would like to embed own diagrams in my doxygen documentation. Is it possible to create your own diagrams using graphviz by textual description inside the sourcecode?
Yes, have a look at the \dot command.
Note that you can also include message sequence charts via \msc. Dia files using \diafile and as of release 1.8.8 also PlantUML diagrams via a \startuml ... \enduml block.
Related
I've been using AsciiDocs to write all my documentation, and i was wondering if i could take it a step further and generate the html from my source code, like how JavaDoc does with Java source code.
For example, JavaDoc allows the developer to leave in-line comments that will later be used to generate the html documentation. Is this possible with AsciiDocs? Or do I just need to write the documentation separately?
Javadoc is somewhat modular and extensible: you can use a custom formatting syntax in javadoc comments if you generate the documentation with a custom "doclet".
For AsciiDoc, such a doclet already exists: https://github.com/asciidoctor/asciidoclet
Javadoc is specific to Java, if you use other programming languages there are other tools. Doxygen was created specially for C and C++ but it supports several programming languages and comment styles. For Python, there is pydoc. Whether there's a way to make these support AsciiDoc syntax, you'll have to investigate on your own.
I am creating a MATLAB package using object-oriented programming. I have documented my classes according to a tutorial from MathWorks website. This standard of documentation, however, only works for doc and help commands, but not when I use publish. For example, properties, which have their description written in front of their declaration, don't have said declaration exported to HTML. There is no list of properties or methods at the beginning of the file, so that users can quickly skip to those. Lastly, documentation has to be read directly from the comments in the code, instead of being parsed to HTML.
When I try to add some HTML documentation inside my classes to publish them, the code also appears on doc and help, which is an undesired behavior. Is there a way to create class documentation so that properties and methods can be published to the Web? I've had experience with doc generators like Sphinx (Python) and Doxygen (many languages), in which the descriptions of classes, methods and properties are parsed to HTML so they can be published in places like Read the Docs or GitHub Pages so I am curious to know if MATLAB has something like that.
You can give a try to MTOC++ which uses Doxygen, therefore produces the standard Doxygen HTML documentation.
I have used it already to generate source code documentation for Matlab project containing standard Matlab functions, old class definitions with # notation and classes defined by classdef mixed, and it worked after some tailoring.
This somewhat larger project allows to create documentation for MatLab
files and classes (including packages) using a doxygen filter named
mtoc++. Moreover, a tool/class named MatlabDocMaker allows to create
the documentation from within MatLab. For Windows, Mac and Unix!
You can find it also on Mathworks File Exchange and you can find the documentation here.
One widely-used way to provide HTML documentation for MATLAB functions/class is the M2HTML project. It will automatically generate HTML documentation complete with dependency graphs, source code, and syntax highlighting.
I have spent the days looking for an Opensource JavaDoc editor or a way to edit JavaDocs easily or creating package-info files and come back empty.
I am basically after a way to change the way the packages are listed. The automation framework I work on is undergoing some potential future changes. These changes in a nutshell will organise our test scripts in a way where they are split up into business areas and then into smaller packages of business functions within that area.
We use IntelliJ and the default JavaDoc generator creates the JavaDocs in a way where it makes a list of all the packages, what I want to do is have it create a list of the main packages (business areas) and then the sub packages within that contain our test scripts (business functions).
For example:
BusinessAreaOne contain BusinessFunctionOne, BusinessFunctionTwo and BusinessFunctionThree.
BusinessAreaTwo Contains BusinessFunctionFour and BusinessFunctionFive.
The BusinessFunction packages in turn contain scripts that cover just that business function.
I haven't been able to find an editor that does what I would like and I don't think editing the files manually is practical each time there is an update.
If there is no opensource java editor can do this are there any suggestions of a work around?
As I mentioned I have tried creating package-info files but as far as I can tell you can only add a description to that package. Is there any tutorials out there or does anybody know a way I can get it to display the list of packages within the selected package?
Thanks in advance.
Javadoc doesn't treat package hierarchies as nested hierarchies, it just flattens them all into a list, as you probably noticed, so your business functions will just appear as entries in the list between the business areas.
Looking for a Javadoc editor is not going to help you because the Javadocs you end up with is the output from the Javadoc compilation process, and there's no specific tag you can put in your code that will influence the compilation process in the way you're looking for.
You would have to write something to override Javadoc's implementation of its HTML formatter specifically for the package list using:
Javadoc Doclets
You can customize the content and format of the Javadoc tool's output by using doclets. The Javadoc tool has a default "built-in" doclet, called the standard doclet, that generates HTML-formatted API documentation. You can modify or subclass the standard doclet, or write your own doclet to generate HTML, XML, MIF, RTF or whatever output format you'd like. Information about doclets and their use is at the following locations:
Javadoc Doclets
You would use your own implementation of the Standard Doclet, finding the right class to override - try looking first at the PackageDoc class. I'm going through this learning process myself at the moment, but here's the info on Doclet and there's a link at the bottom of that page to the source code which will illustrate how to do it.
Of course there could be an easier way of doing it and if I discover it I'll come back to update this answer.
I'm looking for a HTML5/JS based UML editor library, able to support custom UML editor development, for basically Class Diagrams, eventually Package and Component diagrams.
My concrete requeriments:
support of basic elements of UML class diagram (mandatory) and components and packages (optional): classes, attributes, methods, stereotypes, associations (in all flavours), generalization, etc.
Drag & Drop capability from the toolbox (optional)
XMI supprt (optional)
pure JS/HTML5 with eventually some well-known libraries usage
a good control over the model's logical structure and a nice interface to iterate the model
I've already seen a couple of them (GoJS, Jointjs, etc) but would like to see all possible options and maybe some recommendations.
Thanks!
There are libraries to generate UML diagram with those requirements.
JointJs core library is open source under Mozilla Public License, which mean you must include copyright, but you can use it for commercial purposes. It has dependency to jQuery 3.1.1, Lodash 3.10.1, Backbone 1.3.3. (Rapppid is using this library)
It provides many ready-to-use diagram elements, which are responsive and
interactive. User can move blocks, add and remove relationships and
joints, zoom in and out.
Draw2D is library to create Visio like drawings, diagrams or workflows. The community version is almost 5 euro to buy. It indeed provides Visio like blocks and diagrams, which are interactive to resize, move blocks and modify the text and relationships, and grouping blocks, zooming in and out. This can be a good choice to build a graph editor tool.
mxgraph is a library to
build a UML editor like draw.io.
Created blocks are interactive, so the user can move or resize the
block, modify the text, add or remove relationships.
gojs is another library, which is commercial but it provides free licenses available for academic purposes. It is also suitable choice to create UML editor, with many ready-made diagrams available. After creating blocks, user can move them, modify the text and relationships; and many other features for different other diagrams.
UmlCanvas by Christophe VG as js library which provides UML diagram from textual information. The diagrams are responsive in a way that you can move the blocks; and relationship lines are smart to keep the design pretty. But not more than that.
PlantUML is a UML tool that can provide UML diagram from textual information by jQuery libraries (libraries in other languages are also available), however the diagrams are not responsive.
Raphaël is a small JavaScript library that can simplify your work with vector graphics on the web. This is not the best tool to create graph editor, but it provides shiny and beautiful diagrams for simple user interaction (such as movement and bending)
There are other libraries such as:
D3
FabricJS
paperJS
JsPlumb
p5.js
Cytoscape.js
mermaid
They provide basic components for diagrams, but most of them don't have functionality for built-in editor such as drag and drop, and block editing. On the other hand, developer can create different chart and drawing components, which are available by those libraries. They may not be the best option to create fully interactive and editable diagrams for the users.
Take a look at "jsUML2: HTML5/javascript library for UML2 modeling". A short intro can be read here
Note: I realize this question has already been asked (with a ruby slant) here: Creating on-demand, print-quality PDFs (preferably in Ruby if feasible). BUT there was no decent answer IMHO.
So as you may have guessed, I am looking to find the best approach to producing HIGH QUALITY, print ready PDF documents programmatically. Our requirements need us to be able to have design documents that define place holders for dynamic content like images and text i.e. some kind of template mechanism.
The suggestion has been to use Adobe's InDesign server, but this seems like an expensive solution not to mention a little overkill for our need.
Are there any alternative, cheaper and more fitting solutions out there? The language of the solution doesn't really matter, just as long as it can be executes on a Windows box.
My suggestion would be to look at XSL-FO or thereabouts...
You create an XML doc that describes what you want and there are various libraries and toolkits (I've used XEP from RenderX) that will convert said XML into PDF.
In real terms what we did was take a large lump of data in XML format, use XSLT - templates in effect - to convert the data to formating objects which XEP renders up into something (a 500 page hotel directory with auto-generated TOC and Index) that has been consumed quite happily by at least three different commercial printers. We did some other smaller documents too from time to time.
Downside with this is that its not even remotely a WYSIWYG solution - you're effectively compiling "source code" to get PDF out the back. Upside is that the base technologies are reasonably generic even if the specific toolkits may be a bit less so.
You can convert XML templates to PDFs with Prince.
Prince is a computer program that
converts XML and HTML into PDF
documents. Prince can read many XML
formats, including XHTML and SVG.
Prince formats documents according to
style sheets written in CSS.
I have and also know many people that have had much success with ReportLab an open source Python PDF library (http://www.reportlab.org/rl_toolkit.html).
Its extremely easy to use and very quick to get started. So worth trying out.
I don't know why no one has suggested using LaTeX for this. It's an extremely popular open format for document design and not hard to set up a template that you can fill in text or image content. While the reference implementation of LaTeX runs as a standalone program, if that sounds like too many moving parts for you there are wrapper libraries for Python and other languages you can call via an API.
Java language and JasperReports
Java: iText
C#: iTextSharp
depends on what you want to publish, but take a look at Pentaho reporting
http://reporting.pentaho.org/
rinohtype is an open-source document processor that is capable of producing high-quality print-ready PDF documents. You can use one of the built-in document templates (book, article) or define your own template. The look of document elements can be configured by means of CSS-like style sheets. The contents of your document can be parsed from reStructuredText or CommonMark files, or you can build the document tree programmatically.
Full disclosure: I am the author of rinohtype.