Kratos: Discussion about documentation format

[loumalouomega]

Greetings, we have been discussing about the creation of a completely new repository just oriented to documentation, conclusions have been extracted, but of course a deeper and more profound discussion has to be made to paint the final structure of this repository.

This is my proposition:

• The user documentation (manual): The documentation focused for the Kratos (just) users
• The developer documentation (manual): The documentation focused in Kratos developers, C++ tips, data structure, API documentation, etc...
• Theoretical documentation: This documentation is the explanation that underlies in Kratos core and main applications, this can be very interesting for users and developers to understand what underlays in the code.
• Wiki files: The images, files needed to maintain the wiki, right now we are using the ones form the previous wiki, and this is not the proper way to work.
• Presentations: The Kratos presentations in conferences, etc...

In general we can use as reference what is in the FEAP documentation.

@RiccardoRossi In the other hand, GitHub has built-in support for rendering .ipynb files. You can write inline and display LaTeX code in the notebook and GitHub will render it for you. I recommend this approach for the AD documentation, the Jupyter notebooks (previously IPython) are quite powerful, and they can be used for something more than just showing the LaTeX equations, you can show plots and small tests embedded. Try Jupyter

Here's a sample notebook file

[loumalouomega]

@RiccardoRossi To edit online Latex Easy https://www.latex4technics.com/

[RiccardoRossi]

Hi Vicente,

i know pretty well jupyter, but it does not fit to what i am looking for.
what i need is a "what you see is what you get" text editor which allows
editing formulas.

my candidates are lyx or word.

my problem with tex is that formulas are not displayed as you type...which
is exactly the feature i would like to get.

cheers
Riccardo

http://www.cimne.com/

[loumalouomega]

@RiccardoRossi
Jupyter was just the way to put the documentation (Markdown is less powerful and it is a completely new language to learn). This is the way to have a rendered in GitHub README.ipynb

Maybe in that case the easier way is to convert LyX into LaTeX

[roigcarlo]

@RiccardoRossi If I understand correctly, the problem is getting a preview of the formula as you write it? We can just use an external tool to write them and use any format supported by github to display them. There are a lot of services that do just that:

For example, try to type this code:

$$ a = \sqrt{2}$$

here:

https://stackedit.io/editor#

You will be able to edit the equations as you write them, no compilation needed, and as it uses the same engine to render the formulas as Jupyter ( MathJax ) only copy paste would do just fine like @loumalouomega said.

[RiccardoRossi]

Hi Carlos.

This is not what i am looking for.

I need something like Word+equation editor

Google docs is close but diesel not allow multilineal formulas (for example
to write a Matrix)

Lyx would do, bit the formato isnot very Stanley

Also Word would do of course, but It is not cross platform

El 16 feb. 2017 12:43 a. m., "Carlos Roig" [e-mail]
escribió:

@RiccardoRossi https://github.com/RiccardoRossi If I understand
correctly, the problem is getting a preview of the formula as you write it?
We can just use an external tool to write them and use any format supported
by github to display them. There are a lot of services that do just that:

For example, try to type this code:

$$ a = sqrt{2}$$

here:

https://stackedit.io/editor#

You will be able to edit the equations as you write them, no compilation
needed, and as it uses the same engine to render the formulas as Jupyter (
MathJax https://www.mathjax.org/ ) only copy paste would do just fine
like @loumalouomega https://github.com/loumalouomega said.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/KratosMultiphysics/Kratos/issues/26#issuecomment-280179180,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AHr7EZmozNj2EvGytEnadX4naqGe4Tnmks5rc42lgaJpZM4MB83x
.

[loumalouomega]

Please, the think related with the equation editor is a parallel subject, let's focus in the structure of the documentation repository.

[pooyan-dadvand]

I agree with @loumalouomega and @roigcarlo that we should first decide structure and format but not the editor which can be many.

About the proposed structure I think that focus over developers and users is important and I think that even the presentations should be divided depending if is more for developers or users. I would also add a quick start part where the introductions and overviews go.

About the format maybe a good solution is to have the source and pdf of the documents in the same folder so if someone just want to see them uses pdf and for editing the other.

About the format I won't go for lyx as it gives too much compatibility problems. And I think for small equations solutions described here in GitHub would be a good starting point.

[loumalouomega]

I was thinking, and maybe it could be nice to call the documentation project as Athenea (because it is the knowledge of the Kratos project)

[jcotela]

Maybe I'm too booring and unromantic, but I would call the documentation "Documentation" (or, at most "Resources")

[pooyan-dadvand]

I'm booooooooring too. Documentation our Resources are more explicit and easier to understand.
And Athenea sounds another porject: Analysis of THErmal Nonlinear Entropy in Air! :-D

[loumalouomega]

@pooyan-dadvand , can you create the Documentation repository?

[loumalouomega]

@pooyan-dadvand thanks to create the documentation repository, can you please add me as contributor

[roigcarlo]

@loumalouomega I granted you access

[roigcarlo]

@pooyan-dadvand Should add some kind of forced review process as in kratos?

[pooyan-dadvand]

At this moment I don't see that the feature branch is suitable here. So I would leave it with master and as a plain repository and see how it works.

[loumalouomega]

Ok, I will start adding documentation

[roigcarlo]

Just one question, before starting to add things there.

How will this be organized (aside from the formats discussed above). Purely under the point of view of "this file goes here, that goes there"? Github pages approach? we are going to have sparse files there?

[loumalouomega]

I already started, I am a very organised person, my intention was to create sub sub folders as a way of keeping everything organised

[loumalouomega]

For example, I am going to move the used files and images from the old wiki to the repository, my idea is that each file is stored in a folder with the name of the article

[pooyan-dadvand]

@loumalouomega I know that you are an organised person and folder organisation is something common. Meanwhile @roigcarlo is talking about GitHub pages which I'm not familiar with. Charli would you please explain a little bit more what you mean.

[loumalouomega]

I will close this issue, this way we reduce the number of open issues.