Documentation and Architecture description

[shroffk]

Need to describe the architecture and the features prototyped in this project.

[kasemir]

Wiki? Easy to edit, but soon degenerates into a disjunct set of outdated pages.

Google Doc? Very easy to edit, results in one long doc where sections can be rearranges as it grows. Unclear how large it can get, though.

Docbook? Allows moving sections around, formats as one PDF as well as web pages, no size limit. But requires some effort for each update.

ShareLaTeXx?

[claudio-rosati]

Personally I don't like splitting the project between different platforms, so I will avoid Google Doc and ShareLaTeX (nevertheless I'm a big fan of LaTeX).

Docbook is not easy to edit, and I've not found a valid tool to do it WYSIWYG.

So the only alternative to me is wiki. I don't agree on the following statement: "soon degenerates into a disjunct set of outdated pages". I mean, this is true for all alternatives. I we don't synch the documentation as soon as we make changes in the code, all solutions will produce outdated documentation.

The only advange I see in Google Doc is that the "live" documentation can be frozen into a PDF and included into the doc folder of the project every main release.

[willrogers]

I use readthedocs.io for Python. This generates html documentation from markup each time a branch is pushed and hosts it online. You could alternatively host it on a Github pages site.

If you upload the jars to Maven Central, you can use javadoc.io to host javadoc. This would be a nice feature.

[kasemir]

Yes, readthedocs.io is great for publishing documentation.

The Spinx type markup ..

• is easy enough to learn
• can be versioned in git
• turns into html (-> readthedocs.io even hosts it for us)
• can also be rendered as one large latex doc for printout

I've created a repository for Spinx-based documentation and it's published on readthedocs.

See http://phoebus-doc.readthedocs.io

If you want to contribute, let me know so I add write access to https://github.com/kasemir/phoebus-doc . Anybody can of course at any time send pull requests.

[shroffk]

• github understands .rst files and provides very useful edit/preview tools.

[kasemir]

Yes, you can (well, at least I get it that way) press an "edit on github" button right on the http://phoebus-doc.readthedocs.io page, which leads to the github repo, where indeed you can edit the files on the web site, with preview.

Sometimes it's convenient to edit some small text that way. At other times, locally running "make html" is better when you move sections around.

I looked at github also serving the result, but all I found about that was:

• Use a gh_pages branch
• include the 'build/html' output in the repo

Git hub will not create the build/html from the sources. But then readthedocs does that for free. You can even download the pdf, so overall sources on github with content on readthedocs seems ideal for now.

[claudio-rosati]

I like the http://phoebus-doc.readthedocs.io kind of documentation. The only thing I dislike (apart the splash-screen displayed on it on the first page) is that it is on a different github repository. Can it be merged into the phoebus one?

Anyway, I think we should seriously talk about documentation. For the ICALEPCS paper I walked (again) through some other frameworks and all of them have documented:

• how to create a simple, hello-world-like application, mostly used to explain the build system, the module system, how to add libraries, etc.
• how to create a more complex application, exploiting all the aspects of the framework (windows management, actions, menu, toolbars, status bar, selection/context passing, etc);
• API (javadoc);
• (most important) the architecture of the framework!

I think the last item is the most important one, and it had to be provided before any development.

[willrogers]

I think the last item is the most important one, and it had to be provided before any development.

I don't think that's true. Phoebus was a prototype, and it can often (always?) be useful to experiment with your architecture before you make final decisions.

Now is a very good time to document the architecture, to make it clear what decisions have been made and which parts are still undecided.

I don't think that Phoebus is a prototype any more. I hope there will be a concerted effort to make sure that everything is cleaned up in line with the final decisions that are made. I also hope we don't go too far before finding some awkward design decisions that can no longer be fixed (see BOY).

[willrogers]

I also like having the documentation in the same repo as the code. This means that you know whether or not your documentation is up to date. Assuming, of course, that the documentation is kept up to date at all.

[kasemir]

I also like having the documentation in the same repo as the code.

We already know that the phoebus source code repository is not the final location. That's the 1st point on the roadmap, since we're still in the forming phase. Going forward, I see the documentation to eventually be in the same top-level structure. Like ControlSystemStudio/third-party, ControlSystemStudio/.., ControlSystemStudio/.., there'll be phoebus/dependencies, phoebus/core, phoebus/applications/probe, phoebus/applications/display_builder and phoebus/doc.

[shroffk]

So I think this discussing is part of the roadmap. There is a preliminary version on googledocs...we can discuss this at the developers meeting.

Last week we redid the AppDescriptor and the AppResourceDescriptor API's and added new services for this I feel we are still a bit of a prototype here :), We are hoping to add an application or two to confirm if the API's, services, etc... are ready. I was hoping @claudio-rosati s app could be a good test.

For this particular Issue on documentation:

I think there is consensus that http://phoebus-doc.readthedocs.io is nice. If we choose to merge it with the code repo....when we restructure the project into multiple repos, would each repo have its own subfolder for readthedocs?

i.e phoebus/framework/docs/Index.rst phoebus/displayBuilder/docs/Index.rst

Would there be a top level that would build all the documents and create a complete set of docs?

About the java docs, I really liked the javadoc.io however uploading to maven might not happen immediately. @willrogers are there any other alternatives you know of? I know that diirt uses maven to produce a site with the javadocs

[kasemir]

I hope to change the splash-screen displayed on it as soon as possible (it is horrible - sorry to be honest).

Why don't you make that your first contribution to the source code: Create a pull request with a new splash screen image.

[claudio-rosati]

Thet will be my first contribution after ICALEPCS ;-)

[willrogers]

Ideally, generate the Javadoc using Sphinx and host it on the same readthedocs page. We don't get out of sync then.

[shroffk]

Is there a reason Sphinx would be better than https://maven.apache.org/plugins/maven-javadoc-plugin/ ?

https://maven.apache.org/plugins/maven-javadoc-plugin/usage.html we can create javadoc .jars, and a site which can then be hosted on the same readthedocs page

[willrogers]

Well, it just wants to be generated at the same time as the rest of the documentation, preferably on each push to any branch.

[kasemir]

There's a difference between

• Online help, end user documentation
• Javadoc

I see little use in publishing Javadoc. You see that in the IDE when working on the code. The online help or end user documentation cannot be auto-generated.

[claudio-rosati]

I agree with Kay on the javadoc point. NetBeans, for example, automatically shows the javadoc as soon as a library, its sources and javadoc are retrieved from the Maven repository.

[kasemir]

As for sphinx, we can of course keep asking why there is no documentation, and instead of starting to write it, we argue about the format. Advantages of sphinx:

• Easier format than LaTeX
• It is a text-based markup that can be version controlled, other than Word
• You can work on it totally offline, unlike Google Doc
• You can also work on it online on the github web site, with decent preview
• Free rendering and hosting of the HTML as well as PDF download on readthedocs

[kasemir]

Last week we redid the AppDescriptor and the AppResourceDescriptor API's and added new services for this I feel we are still a bit of a prototype here :), We are hoping to add an application or two to confirm if the API's, services, etc... are ready.

Right. Kunal and I are adding applications (probe, PV tree, PV table, PV list, logging configuration) to develop and test this as a control system framework. We're not trying to create the ultimate framework for everybody. For instance, ProcessVariable is a key object in core. This is not a framework for a DVD collection management tool.

The two of us are doing what we can to implement control system tools that we will need at our site:

• generic (logging config)
• tools that need a PV, so that PV should be saved and restored when you close/reopen the app (probe, PV tree, ..)
• tools that have 'file' as input (PV table)
• singleton apps, where opening 'another one' will just pop an existing one back to the top (PV list)

This would be a great time to join, trying to add some functionality that we don't have on the roadmap because it's specific to your site. Or pick some piece from the roadmap. Or try to understand what's there and write the documentation.

[claudio-rosati]

I hope the framework will be partitioned in a way to be able to create a non-PV based application just using the UI services. I'm not thinking to a DVD collection management tool (why not?), but OpenXAL application, where the PV connection is already realised differently.

[kasemir]

Just to clarify, core-types has ProcessVariable as basically a name that's used to attach context menus, to drag/drop. And there's the core-pv with the code for actually connecting, reading, writing. You could use core-framework without those. But core-ui depends on all the above.

If you have a control system related feature that is essential for your site that would benefit from splitting core-ui into parts that are fully generic (docking) and those that are aware of PVs, that'd be something you could start with a pull request. Right now as everything is one git repo is a good time for that, because it's just one pull request, no need to coordinate pull requests to N repos that all need to happen "at once" as code moves around.

[claudio-rosati]

So, what I think that ProcessVariable could inherit from a ContextContent (or SelectionContext, or just Context) in core-ui. This will render it more generic and, maybe, making easier to have core-ui independent from PVs.

P.S. I didn't have time to clone the repository and digging it, so I apologise if my comments could be a bit "out of context".

[willrogers]

I think I disagree on Javadoc. Your IDE shows it if you have it correctly configured and have the right bits imported. Often (Eclipse libraries for example) I don't get the Javadoc correctly. I'm often searching Javadoc online.

Plus:

• It's free, once you can generate it from your code
• It encourages you to document classes and methods properly

[kasemir]

(Eclipse libraries for example) I I don't get the Javadoc correctly Really, for the eclipse code? I assume that means you're not using the RCP & RAP development version of Eclipse.

I do have that problem for diirt, when I'm forced to use the maven-downloaded binaries and thus don't have the source code: No javadoc, no source-level debugging.

That's why I've been arguing for 1) Download the sources 2) Import into the IDE 3) run

instead of having maven fetch something from somewhere, and then you at best get the binaries, and the rest it left to the reader as an exercise.

I do agree that every bit of 'public' source code, i.e. the API for docking, PVs, selection, application description, .. must have javadoc. Please let us know if anything is out there that lacks javadoc. I'm also not opposed to publishing the javadoc separately, but again that is no replacement for a manual.

[kasemir]

.. have documented: .. (most important) the architecture of the framework!

True. As Kunal mentioned we're still trying to figure many details out, but it's probably ahead enough to give a basic overview, so see http://phoebus-doc.readthedocs.io/en/latest/architecture.html

[kasemir]

The Tango project decided to move all their documentation to http://tango-controls.readthedocs.io, also using github to host the spinx doc. Encouraging to see another example that uses it for documentation at large, i.e. beyond Python.

[shroffk]

https://control-system-studio.readthedocs.io/en/latest/architecture.html