Doc is missing - Githubissues

FerreolS commented 3 years ago

Should we add button displaying the doc for the different algorithm or just rely on an external website?

buthanoid commented 3 years ago

My point of view is :

nothing can be more complete and efficient than an external website, so obviously we should not aim at being perfect and always include a link to an external website.
a live accurate sign concerning keywords for example, is very efficient, for example take IDE that displays information about parameters, their types, and short description of a method when you hover it with the mouse. It is incomplete but very efficient. Is such thing would be useful for algorithms parameters for example, it would be a good functionality to add. Same would be for displaying a average-sized description of the algorithm. Something between the "memory aid" and a synthetic explanation of the algorithm.
if we are aiming at very beginners users, this cannot replace a demo with either a video, either a "guided GUI tour" with popups indicating the user the current step and what to do. This is a lot of work.

FerreolS commented 3 years ago

After discussion with Antoine, we propose to add an help button near the algorithm menu. This will show a popup with a brief summary of the method, the description of (and only) the keyword accessible through the GUI, and a link to the algorithm webpage

bourgesl commented 3 years ago

Please give documentation for MIRA (description, meaning of keywords & possible regularisations) as a good start to implement the popup window

FerreolS commented 3 years ago

MiRA

Multi-aperture Image Reconstruction Algorithm: MiRA: a Multi-aperture Image Reconstruction Algorithm

INIT_IMG : initial image
RGL_WGT : hyper-parameter tuning the strength of the regularization
Regularization functions
- Compactness: (aka soft support) favors compact solutions where images structures are concentrated within a region of full-width at half maximum RGL_GAMM (in mas).
- hyperbolic (aka Edge-preserving smoothness) favors smooth solutions while allowing sharp edges significantly higher thanRGL_TAU. Using a very small RGL_TAU compared to the norm of the local gradients, mimics the effects of total variation (TV) regularizations.Conversely, using a very small edge threshold yields a regularization comparable to quadratic smoothness.
Bandwidth smearing (chromatic aberration caused by the finite width of the spectral bandwidth)
- SMEAR_FN : function modeling the effects of the spectral bandwidth smearing. Can be none if there is no bandwidth smearing, sinc for a cardinal sine or gauss for Gaussian (whose full-width at half-maximum matches that of the cardinal sine)
- SMEAR_FC : strictly positive factor to scale the effects of the spectral bandwidth smearing. The full-width at half-maximum of the effective spectral bandwidth is assumed to be equal to SMEAR_FC times EFF_BAND parameter in the data. The default is 1.0

Reference

Thiébaut, É.: "MiRA: an effective imaging algorithm for optical interferometry" in SPIE Proc. Astronomical Telescopes and Instrumentation 7013, 70131I-1-70131I-12 (2008) DOI.

FerreolS commented 3 years ago

This is the type of doc I plan to have for each algorithm. It should show on a pop-up when clicking on a doc button near the algorithm. A nice feature should be to have this doc written in markdown files somewhere that can be fetched during build. It will be easier to maintain.

bourgesl commented 3 years ago

Great, you could add authors, contact email ? maybe citation / license terms ?

Please create 1 text document per software in the doc/ folder (markdown, plain ASCII or html ?), anyway we'll manage how to parse & display them in the GUI.

FerreolS commented 3 years ago

Indeed, we could add a citation. The rest (licence, author, e-mail ) are on the webpage pointed at the second line. I believe that if there is MiRA.md, WISARD.md and BSMEM.md in the doc folder it will be very easy to update (even directly from github)

I have edited https://github.com/JMMC-OpenDev/oimaging/issues/11#issuecomment-947099219 accordingly

buthanoid commented 3 years ago

Decision needs to be taken about choosing between the two following alternatives: 1) the help button opens a tab in the user browser, to a web page containing documentation 2) the help button opens a dialog in OImaging, displaying documentation, and a link to a more complete web page

If we choose Option 1), we can directly host the markdown file on github, either in the repository, or in the "wiki" pages. Github will already display "beautifully" the file, with CSS and stuff.

If we choose Option 2), we need to remark than choosing Markdown have some consequences. A markdown parser needs to be added to the project, and it is not as small as someone would expect for a "simple" markup format. Moreover, parsing the same file, at every run of OImaging, is a waste of computation resource. Considering than the documentation will (IMHO) hardly be rewritten more than once a year, parsing the Markdown once, at the time of writing, and storing it in another format (i.e HTML), will permit to avoid the repetitive parsing. Also, modifying an HTML file, just for updating a hyperlink for example, is not difficult for the maintainer of the documentation (all the tedious part have been done at the initial parse).

Also, the Swing simple HTML displayer is a bit outdated ; AMHO it is sufficient for timeless tags like lists and stuff. But Laurent has proposed to use ASCII art which could be sufficient for a simple documentation dialog. Ascii art won't have clickable hyperlinks, but we could find a workaround without much struggle.

FerreolS commented 3 years ago

I think that opening a tab in the browser is often annoying but if everyone think it is a good solution, I'm fine. For the solution 2, is it possible to parse the md only during building? I think a short markdown doc is really easy to maintain. Probably we can also use such a dialog for tutorial.

bourgesl commented 3 years ago

I agree with ferreol that markdown files are the reference files maintained by scientists in /doc folder. We could try converting such files to HTML (v3 for swing html viewer) or plain ASCII manually using a shell script, that can be easily displayed in the OImaging GUI (simple): to be tested.

bourgesl commented 3 years ago

I used https://markdowntohtml.com/ to convert mira.md to mira.html (added html/body tags) and it looks good enough:

mira html_198

        final String doc = "mira.html";
        final String html = FileUtils.readFile(new File(TEST_FOLDER, doc));

        ResizableTextViewFactory.createHtmlWindow(html, doc, true);

bourgesl commented 3 years ago

@FerreolS please write the other markdown files in /doc.

buthanoid commented 3 years ago

development spec proposal:

add jButton in the GUI, at the right of combobox of softwares in softwareSettingsPanel
add documentation:String field in Service class, initialized to null
add getDocumentation() function in Service class, return documentation field, but if null, previously try to read a file named after the service program field (like "mira-ci.html") in the resources folder.
there is the class fr.jmmc.jmcs.util.ResourceUtils with methods to load resources
there is the class fr.jmmc.jmcs.gui.component.ResizableTextViewFactory made for displaying a window with html content
markdown files are to be placed in "doc/" folder
html files are to be placed in the same folder, same name but ".md" extension replaced by ".html"
when updating a mardown file, the programmer must manually convert with ttps://markdowntohtml.com/ and send a commit with both markdown and html updates
there is the help image at jmcs/src/main/resources/fr/jmmc/jmcs/resource/image/help_icon.png (or even at fr.jmmc.jmcs.gui.util.ResourceImage.HELP_ICON.icon() )
there is a "icon" property for swing buttons, I need to check that it is the good thing to use

bourgesl commented 3 years ago

Documents (md html) are stored in the doc folder: https://github.com/JMMC-OpenDev/oimaging/tree/master/doc

Maven build script will copy these files at the right place in the jar file.

FerreolS commented 3 years ago

when updating a mardown file, the programmer must manually convert with ttps://markdowntohtml.com/ and send a commit with both markdown and html updates

I strongly disagree with manually converting md to html. There is too much risk of discrepancies between both. It must be done during build. For example using: pandoc --standalone doc.md

bourgesl commented 3 years ago

As you are responsible for doc, please push md / html in the same commit.

FerreolS commented 3 years ago

No! It has to be done automatically. We should not have to maintain doc on 2 file-format at the same time. Just adding a line with pandoc at the build seems manageable.

bourgesl commented 3 years ago

Please do.

bourgesl commented 3 years ago

See github urls: https://docs.github.com/en/rest/reference/markdown

FerreolS commented 3 years ago

Do you mean that you prefer a github action to automatically translate the md in html? That could be a solution. Please be clearer on what are the issue you see with automatic translation.

bourgesl commented 3 years ago

I just wanted to not waste my time on writing shell or build script, but I did: See /doc

FerreolS commented 3 years ago

Super. Thank you Laurent

buthanoid commented 3 years ago

https://github.com/JMMC-OpenDev/oimaging/pull/45

Did not included yet your new documentation. I don't have time today anymore.

I used a bash script because it permit to not fail compile phase in case pandoc is not available. I assumed bash should be available more often.

buthanoid commented 3 years ago

I added a profile in the POM to prevent activation of the plugin calling parsing bash script. Because if you are on windows, or if you don't have /bin/bash, the plugin fail to complete, and make the whole compile phase to fail, and I did not found how to prevent this. My best try was then to prevent the activation of the plugin if conditions are not met. https://github.com/JMMC-OpenDev/oimaging/pull/45/commits/bf87d8fbfe1b057fa7c7f48f9ab51fb75586e1df

Note that the copying of the HTML files to the resources folder is always working because it relies on a well known maven utility that should be very portable.

I merged and changed the names "wisard.md" to "wisard-ci.md" so it uses the getProgram() String registered in Service objects. I took the script from Laurent which was better, I just added a presence test of pandoc command. https://github.com/JMMC-OpenDev/oimaging/pull/45/commits/4342b1161ccd789ae91153b47a4db1140572b234

buthanoid commented 3 years ago

Changé le profile de parsing pour qu'il ne s'active que quand l'option devMode est true. Corrigé les phases des plugins.

bourgesl commented 3 years ago

see #46 done

JMMC-OpenDev / oimaging

Doc is missing #11

MiRA

Reference