search

JuliaIntervals / IntervalLinearAlgebra.jl

Linear algebra done rigorously
MIT License
36 stars 9 forks source link

add FEM example to documentation #105

Closed jorgepz closed 2 years ago

jorgepz commented 2 years ago

PR description

A FEM example page is added to the documentation.

codecov-commenter commented 2 years ago

Codecov Report

Merging #105 (4668bb0) into main (18db5d5) will not change coverage. The diff coverage is n/a.

Impacted file tree graph

@@           Coverage Diff           @@
##             main     #105   +/-   ##
=======================================
  Coverage   90.96%   90.96%           
=======================================
  Files          14       14           
  Lines         487      487           
=======================================
  Hits          443      443           
  Misses         44       44

Continue to review full report at Codecov.

Legend - Click here to learn more Ξ” = absolute <relative> (impact), ΓΈ = not affected, ? = missing data Powered by Codecov. Last update 18db5d5...4668bb0. Read the comment docs.

lucaferranti commented 2 years ago

Fantastic, thanks a lot!

A couple of comments

  1. I think this would better fit under "applications" folder?
  2. To actually tell Documenter.jl to include the page in the documentation, you should also update the website structure in docs/make.jl. In this case the line linked could be changed to applications => ["Title " => "path/to/file"],. Or was it intentional to leave it out for now?

(Note to myself, I should add a note about how to add new pages to the docs in the contribution guidelines)

jorgepz commented 2 years ago

Hi. I made the changes you suggested. What do you think about writing all the matrices in the markdown? In case we write them all, I think that a good option is to write the example using Literate.jl and generated the matrices of the example with a code directly...

lucaferranti commented 2 years ago

Writing all matrices in markdown sounds indeed painful. I like the idea of using Literate.jl. I think there are two options

1) we update the docs/make.jl file to call Literate and automatically generate the markdown files from it when deploying,

2) we manually generate the markdown locally with Literate before pushing.

The second one is kind of quick and dirty and maybe ok for just one tutorial, the first one is I guess more robust and professional.

Which one do you prefer for this PR? I'd be glad to setup the Literate+Documenter workflow for you if you don't want to dig into that

jorgepz commented 2 years ago

Indeed option 1 is the best. I'd be glad if you can set the Literate+Documenter workflow πŸ‘πŸΌ That would be the best for us all 🀣 I can stand by for that and continue after that.

lucaferranti commented 2 years ago

There are a few issues with the equations with the arrays, I guess because of the missing \end{matrix}. Btw, did you know you can do \begin{pmatrix}....\end{pmatrix} to directly get the matrix with parenthesis πŸ˜„ ?

I'll get Literate + Documenter workflow setup, hopefully by tomorrow

jorgepz commented 2 years ago

Excellent! Thanks for the tip pmatrix. I was not able to see the deploy of the docs neither generate the html locally, then, I was not able to see the result. Don't hurry for me, these days teaching is intense for me 🀣

lucaferranti commented 2 years ago

I've added the Literate+Documenter integration, just rebase this PR and should be ready to go.

Now the docs has a subfolder literate where to place the scripts that Literate will convert to markdown before deploying the docs, so in this case adding a literate/applications/FEM_example.jl should be enough, the make.jl script will (should!) take care of creating the markdown file and putting it in the right place.

I have also enable documentation preview on PRs, so next time you push it will also deploy the docs and you will be able to preview it

lucaferranti commented 2 years ago

Ah I had forgotten that the preview feature is available only if the PR is opened from a branch in the same repository, sorry for that :/

If you want to deploy it locally to see what it looks like, in principle navigating into the docs folder and calling

julia --project make.jl

should be enough. Then by opening docs/build/index.html you can check what it looks like. If the previous step failed, then it's likely I have some weird boo-boo in the docs that for some reason went undetected so far.

Anyway, I was able to clone the PR and deploy that locally, so I can check that everything looks fine

lucaferranti commented 2 years ago

I fixed a few latex/literate issues. Regarding the figure, when I deployed locally the diagram itself was relatively small and it had a huge white background around it. How was the figure created? I think iin some softwares sometimes you have to manually "crop" the image to avoid a huge white background around it

jorgepz commented 2 years ago

I fixed a few latex/literate issues. Regarding the figure, when I deployed locally the diagram itself was relatively small and it had a huge white background around it. How was the figure created? I think iin some softwares sometimes you have to manually "crop" the image to avoid a huge white background around it

thanks for the comment. I am using Inkscape. I generated the png and moved it to the assets folder.

jorgepz commented 2 years ago

closed to continue working on #111 from the repo