search

plantuml / plantuml

Generate diagrams from textual description
https://plantuml.com
Other
9.73k stars 881 forks source link

plantuml Documentation project #67

Closed VladimirAlexiev closed 3 years ago

VladimirAlexiev commented 6 years ago

plantuml is an amazing tool and @arnaudroques provides amazing speed of innovation and a great support to developers and requests.

However, plantuml documentation is just sad: extremely outdated and fragmented across several places. I consider myself an advanced user (eg wrote a rdfpuml generator of diagrams from RDF data), and still I'm sadly surprised that I don't know half of its features. Just today I learned of

I mostly use http://plantuml.com/class-diagram, and it doesn't describe all features. Another complication is that many features are described redundantly, eg Tooltips should be described in one place with a matrix stating where they are supported.

It's obvious to me that plantuml will flourish (people are asking for Venn, MindMaps, etc etc). But when something is not documented, it's used by perhaps 1% of the potential users. Furthermore, plantuml has a peculiar syntax, and if it's not meticulously documented for every feature, people can't use that feature.

So I'm willing to put a lot of time to make proper plantuml documentation, and help @arnaudroques and other contributors keep it up to date.

Sources (ADD MORE if you know others):

I think the best production method is Markdown (though I prefer Org-mode). @arnaudroques, how do you make the web pages?

VladimirAlexiev commented 6 years ago

For better comprehension, I compressed the skinparam list in the form of regexps (See below). I use "_" to indicate an empty alternative, and have overgeneralized the regexps a bit in order to keep them simpler. image

VladimirAlexiev commented 6 years ago

features are described redundantly

And non-orthogonally. Eg the Class page doesn't say anything about arrow color. http://plantuml.com/incubation talks of "Change line color in state diagrams". On a hunch, I took the example there and modified it to a class diagram with arrow colors and voila! It works.

This is a very important feature for me that I completely missed because it's not documented properly.

webpages a bit hard to read due to all the ads

Another big defect is that there are no anchors. Eg I can't refer to http://plantuml.com/incubation "Change line color in state diagrams" by a direct URL :-(

VladimirAlexiev commented 6 years ago

To be fair, http://plantuml.com/sitemap-language-specification lists Archimate documentation. Because it's not in the top header, it's easy to miss.

aadrian commented 6 years ago

@VladimirAlexiev especially sad that ERDs are not documented nor are there any nice examples.

IMHO it could be the main selling point for PlantUML since most projects with some sort of DB persistence need an ERD to document it.

VladimirAlexiev commented 6 years ago

I just found that http://plantuml.com/PlantUML_Language_Reference_Guide.pdf Language Reference Guide is updated to Version 1.2017.15. So @arnaudroques please accept my apologies for a bit harsh tone above, and an offer for help if you need any with keeping the docs up to date. Cheers!

arnaudroques commented 6 years ago

@VladimirAlexiev No problem! We know that the doc is far from perfect...

aadrian commented 6 years ago

@arnaudroques where is the source of the http://plantuml.com/PlantUML_Language_Reference_Guide.pdf so we can contribute to it?

arnaudroques commented 6 years ago

@aadrian The situation is complex... There are no raw source for http://plantuml.com/PlantUML_Language_Reference_Guide.pdf More precisely, there are a source using an internal custom format that is used to:

We thank you for your help proposal. I think we should rebuild our "custom" format to something more standard (Markdown for example) using https://github.com/vsch/flexmark-java However, this is a large work, so we probably need contribution here

VladimirAlexiev commented 6 years ago

@arnaudroques Single-sourced documentation is the best (esp because you have so many examples, and I am sure you regenerate them automatically). I think we can work with this flexmark format. Please make a parallel repo plantuml-doc and put your doc sources out there, and start accepting contributions.

For example, today I've spent an hour figuring out how to check the puml and dot versions of a newly installed server.

weedySeaDragon commented 6 years ago

If I possibly can, I would be happy to help with the documentation. I totally agree with @VladimirAlexiev -- PlantUML is powerful, but the doc has not kept up.

Would be great to generate the documentation based on the codebase. This will assume that the appropriate info and some markup is in the code, but more than pays off with the all of the advantages and labor saved with having a single source.

weedySeaDragon commented 6 years ago

Yet another thought: Sphinx is used to generate documentation and websites. It's easy to put it into a maven or ant workflow.
At it's simplest, it takes markup files and generates output (HTML, text, and PDF via LaTeX). It supports internationalization (translations).

There are lots and lots of plugins that can do things like process source code as part of the input to the documentation. That means that the source code can be the single source of information for the documentation content. (Of course you also provide things like HTML templates so that you can generate your website as you want it, etc.)

There's even a plug-in that can read PlantUML files and insert the diagrams.

I've forked this repo and am playing with it on my local machine.

VladimirAlexiev commented 6 years ago

As @arnaudroques wrote above, he's using an internal custom format and plans to perhaps convert it to Markdown using a Java implementation. Sphinx uses Restructured Text and is implemented in Python, so it may or may not be useful. Its particular strength is in defining a document tree/TOC and hyperlinks between doc modules.

weedySeaDragon commented 6 years ago

Sphinx can use markdown as input. And there's a maven plugin so that you can run Sphinx as part of the workflow: https://trustin.github.io/sphinx-maven-plugin/index.html That plugin also gives you the ability to incorporate plantuml right into the documentation (using rST).

Right now on my local machine, the maven task site runs Sphinx to generate some simple site pages.

So it might be possible to get the output of java -jar plantuml.jar -pattern and turn that into rST (doing some basic substitutions on the regexp patterns to turn it into something 'end-user readable'). Or take the output of java -jar plantuml.jar -help for a page on all of the command-line stuff.

But -- I'm just suggesting Sphinx as a possibility. It may not be the right tool for the job.

(IMHO, Sphinx has many more strengths than just a document tree. YMMV)

albfan commented 6 years ago

@arnaudroques http://translate.plantuml.com/ looks a lot like sphinx-intl

https://pypi.python.org/pypi/sphinx-intl

See https://bugzilla.gnome.org/show_bug.cgi?id=789008

for an example usage. I guess generated po files can be reworked for that frontend

For sphinx and plantuml integration see readthedocs

http://build-me-the-docs-please.readthedocs.io/en/latest/Using_Sphinx/UsingGraphicsAndDiagramsInSphinx.html#using-plantuml

It is just add 

extensions = ['sphinxcontrib.plantuml']

to conf.py

Then you can have a great documentation on a responsive website and pdf or other formats if you like too

Let me know if you want to migrate, I would love to help out

arnaudroques commented 6 years ago

To help us to improve the documentation, we have just put in place a Wiki here: http://wiki.plantuml.net This is really a try and we expect this wiki to be the single source of documentation in some future.

Potherca commented 6 years ago

I know this might not be a popular opinion but I would strongly advise against (ab)using a wiki for documentation.

The major drawback are:

I would very strongly advise to use a more common solution instead, like a separate repo, the Github Wiki, readthedocs or any other simple-markup oriented solution.

Consider: the documentation for an open-source project the scale of PlantUML is a project in its own right. It is a lot easier for contributors to make additions and changes through the Github platform than in a wiki. It is also a lot easier from a maintainers perspective to keep track, delegate tasks and orchestrate contributions here.

I know this is not my place to make demands but I would really really strenuously ask you to reconsider using a wiki.

VladimirAlexiev commented 6 years ago
arnaudroques commented 6 years ago

@VladimirAlexiev Yes http://wiki.plantuml.net/site/plantuml-text-encoding is supposed to be the source of http://plantuml.com/pte so there is an issue here. I'll investigate about this.

VladimirAlexiev commented 6 years ago

Aha! And I added a link from http://wiki.plantuml.net/site/plantuml-text-encoding to http://wiki.plantuml.net/site/server#metadata:

"The encoded metadata is stored in the generated PNG, so the diagram source can be extracted from the diagram itself!! (see metadata)."

arnaudroques commented 6 years ago

@Potherca Ok I agree with you on this:

Consider: the documentation for an open-source project the scale of PlantUML is a project in its own right. It is a lot easier for contributors to make additions and changes through the Github platform than in a wiki

I really like to set PlantUML documentation as a project on its own. My biggest concern is that today the documentation (although incomplete) is partially translated in French/Spanish/German/Japanese/Chinese/Korean/Russian so this is something I would like to keep. And I did not find any tool that would allow collaboration and easy translation. That's why I've tried DokuWiki : its translation plugin looks fine.

But if someone find some better way to manage those translations using GitHub, that would be something I could put in place.

arnaudroques commented 6 years ago

@VladimirAlexiev and you can use -encodeurl or -decodeurl in the command line flags to encode or decode the text.

VladimirAlexiev commented 6 years ago

Made some edits, the wiki isn't that bad at all! It is very accessible even to non-tech users. The main shortcoming is that there's no TOC/tree, but we can make one!

I think that improving the master documentation (English) and translating it are two separate tasks, and they shouldn't be intermixed. I.e. we should run a half-year English doc improvement effort, after which organize translation efforts.

arnaudroques commented 6 years ago

@VladimirAlexiev pte is now on http://plantuml.com/text-encoding

So I've create a test project https://github.com/plantuml/wiki1 with current wiki sources. So maybe it will give some ideas to someone on how easily manage translations, which is my first concern.

aadrian commented 6 years ago

@arnaudroques very good step. What wiki syntax is using however?

arnaudroques commented 6 years ago

@aadrian It's DokuWiki syntax (see http://wiki.plantuml.net/wiki/syntax ) Note that I'm testing DokuWiki now because its translation feature seems to be the most adapted to PlantUML needs, even if it's far from perfect.

mlopezgva commented 5 years ago

If it is going to remain in its own server (it is only fair...), I suggest the creation of a documentation site using bootmark, strapdown or anything with similar functionality (to mix many sources into one big page with side index and anchors everywhere).

It would be easy to maintain and to update, and adding section auto-numbering, etc.

AsciiDoc is more powerful than markdown and also allows having a TOC an other niceties. Also, AsciiDoc exports "natively" to PDF and, more interesting (at least for people like me that uses vim), to UNIX's manpage format.

Ads can be added, too, because these libraries act upon a single HTML element, and anything else is only altered by the CSS (bootstrap in both cases).

There must be a TODO control list for all the things that needed to be documented.

weedySeaDragon commented 5 years ago

@mlopezgva - Sphinx does all of that. It produces a TOC and an index (which I think is critical). You can create different formats (html, pdf, etc) as needed. And it's been in use for years and has a very large user base. https://read-the-docs.readthedocs.io/en/latest/ works with sphinx: you can use it to generate a website based on source in a github repo (via a webhook)

I've started some documentation with it: https://plantuml-documentation.readthedocs.io/en/latest/

We can also use it with translations (i18n)

mlopezgva commented 5 years ago

The main difference, as see it, is that with Sphinx the site must be generated each time there is a change in a source file, while using some of the others (asciidoc or markdown, or even rst if I'm not mistaken), the site is generated on-the-fly, there's no pre-processing, compiling etc. OK, it is only necessary when the documentation source changes, not every time a page is presented (if I got it right). And, of course, it is perfectly feasible to automate it.

From my point of view, having "only" the [page_name].{md,rst,adoc} files categorized by the directory structure as source of the project is as easy as it can be, and a simple front-end to parse them client-side makes it even lighter to the server. also, making changes means having to change exactly the file which needs to be changed, no more; no compiling, no extra processing at all, just a git push to the server from the repository.

I could even argue no java or java-only-web-server is needed, but since plantuml is already a web java server, that's no point in favor here.

Creating a PDF, man pages etc. could be done using pandoc or asciidoc[tor]. Here there is really a need to run the compiler on each commit to keep the links synced, just like with Sphinx... But only for those formats, not for the web.

But, it is just my opinion. More people have more experience with these and many other tools. I just like to keep far away from java. :-) (our local plantuml server runs with Apache server and 50 lines of script code, no Tomcat or Jetty there...).

weedySeaDragon commented 5 years ago

2 separate issues:

  1. Sphinx does not need to run every time a page is presented. It simply generates the output, be it html or pdf or whatever. If it's html, then just like any other site, it's up to the webserver to present it.

  2. Which tools to use (sphinx or whatever): I think first an agreement as to what the requirements and constraints are is needed. Then the appropriate tool can be chosen.

For complete user documentation, an index is necessary. One critical function that an index provides that is often overlooked is that it provides a list of what is possible and available. (A table of contents provides a very small version of this.) This is a critical and substantial portion of information that has been missing from PlantUML.

I'm unfortunately short on time ATM. We need to agree first on the requirements and constraints. Here's a short list just as a start:

Requirements

Constraints

mlopezgva commented 5 years ago

Hi!

OK, so Sphinx is like Asciidoc, translates RST files into HTML, is not a "live" presenter. I thought it was. Sorry.

Indexing is also possible in asciidoc, but, if rst is preferred, then so be it. I think github also accepts RestructuredText

VladimirAlexiev commented 4 years ago

I've been contributing documentation to the doc wiki http://wiki.plantuml.net/site/index: it works very well! Now most website pages have a link "You can contribute on this page by clicking here".

So let's close the discussion about other documentation toolkits and workflows, be thankful to @arnaudroques and get to work!

@aadrian @albert-github @weedySeaDragon @albfan @Potherca @mlopezgva @mhaaz:

plantuml has a bunch of undocumented features listed at https://forum.plantuml.net/7095, https://forum.plantuml.net/7140 thanks to @Anthony-Gaudino. I think the first urgent task is document all these. All of them have a working diagram towards the end, so it's a "simple" matter of:

Any volunteer to organize the work?

@arnaudroques you could help us by:

<columns 100% 50% ->
<code>
@startuml
...
@enduml
</code>
<newcolumn>
<uml title="foo">
...
</uml>
</columns>

I want to write just that:

<puml>
@startuml
...
@enduml
</puml>
VladimirAlexiev commented 4 years ago

I compressed the skinparam list in the form of regexps

Now updated at https://github.com/VladimirAlexiev/plantuml-skinparam

VladimirAlexiev commented 4 years ago

Set up a channel at https://app.slack.com/client/TL8BFRV6G/CNN19STHC/thread/CKY153BDY-1563199828.000900

VladimirAlexiev commented 4 years ago

Posted detailed task list https://github.com/plantuml/plantuml/issues/261

VladimirAlexiev commented 3 years ago

Thanks to Arnaud, it's now really easy for people to contribute doc additions and fixes using their favorite syntax. Most of the important Wanted Features are now implemented, and Arnaud will be adding more. I'll close this issue because I think most features discussed above are summarized well by Arnaud in this link. If I missed something, please add it to that link, pointing back to the more detailed discussion here.

Now it's time for the community to step up and help Arnaud document this wonderful program better! Eg help by working on the 100-200 categorized tasks in #261