MooseDocs website for Ferret

[mangerij]

Use the MooseDocs system to create a website for Ferret.

[mangerij]

@cticenhour I do have a question (we can discuss on this issue instead of the closed PR):

I was linking parts of input files of the ferret/tutorial folder to the website tutorial pages and it does not like if I change the ferret/tutorial folder. For example, if I rename problem1.i to single_domain.i and put it in a folder located at

ferret/tutorial/single_domain

It says something about running the moosedocs.py command. What exactly is that?

[cticenhour]

I would have to see the exact console message to be sure, but generally if you are moving files around while serving the page, MooseDocs gets upset. It develops an initial file table based on git ls-files, so it sees what you have committed or staged to be commited in the repo. Anytime you are actively moving things around, thereby creating "new" files that MooseDocs doesn't know about, you need to make sure you stage those and then re-run MooseDocs so that it can become aware of that new file.

[mangerij]

Yeah, that's it. Definitely has to do with moving files around. So I guess the procedure is then to always update the git ls-files if I change anything in the main Ferret repo related to tutorial files that I want linked. thanks!

[mangerij]

What is the procedure for generating the links ? For example, if I add a new file to the main repo and want to link to it within the /docs/content? I checked your Zapdos macro and don't see anything that I think is relevant. I could be wrong of course!

[cticenhour]

If its code or input files you want to include, you want to use the MooseDocs Listing Extension. You can see an example if this in use for a whole input file and a GMSH mesh file in the electromagnetics module, though this isn't limited to just inputs or support files - you can even produce blocks that show a particular C++ method in your source code.

For future reference, I should also link the landing page for the MooseDocs syntax documentation.

[mangerij]

Thanks.

Let's say I add a new file input.i to somewhere in the repo and now I want use !listing to link some part of it in the docs. What command do I use so that when I build the docs, the new file can be seen? Otherwise it throws an error.

IS it ./moosedocs.py generate FerretApp?

[cticenhour]

!listing input.i should just render automatically during the build process. No extra work involved. If this is a brand new file, not known by git, then I could see it not being to find the file. Can you give me a snippet of the failing output?

[mangerij]

Yeah, seems I need to commit it.

MooseDocs.base.readers (ForkProcess-19): 
TOKENIZE ERROR: tutorial/input.i does not exist in the repository. The command 'git ls-files' is used for locating files, so the desired file must be committed or staged prior to running moosedocs.py

So I guess I should just get used to first pushing files to git and then running moosedocs and then pushing the doc changes. I suppose I answered my question !

[cticenhour]

You don't need to push - getting it in your local git database is enough:

git add tutorial/input.i

to stage it is sufficient.

[mangerij]

Yup, that worked. Awesome!

[mangerij]

@cticenhour when working on this, I noticed that if I remove a bunch of objects from the main repo of Ferret, the docs system still searches for the objects when building the syntax list. Did I do something wrong? I tried also to rerun the build FerretApp step as well...

[cticenhour]

What errors or messages are you seeing? When you remove objects did you also remove the connected stub documentation files for those objects in your doc/content directory?

[mangerij]

For example,

MooseDocs.base.readers (ForkProcess-10):
TOKENIZE ERROR: '/Kernels/UncoupledGrainBoundaryPhaseIndicator' syntax was not recognized.
/home/ferret/doc/content/source/kernels/UncoupledGrainBoundaryPhaseIndicator.md:19
  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
19│                                                                                                │
20│                                                                                                │
21│!syntax inputs /Kernels/UncoupledGrainBoundaryPhaseIndicator                                    │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘
Traceback (most recent call last):
  File "/home/moose/python/MooseDocs/base/lexers.py", line 230, in tokenize
    obj = self.buildToken(parent, pattern, info, page)
  File "/home/moose/python/MooseDocs/base/lexers.py", line 307, in buildToken
    obj = super(RecursiveLexer, self).buildToken(parent, pattern, info, page)
  File "/home/moose/python/MooseDocs/base/lexers.py", line 257, in buildToken
    return pattern.function(parent, info, page)
  File "/home/moose/python/MooseDocs/base/components.py", line 122, in __call__
    return self.createToken(parent, info, page, settings)
  File "/home/moose/python/MooseDocs/extensions/command.py", line 125, in createToken
    token = obj.createToken(parent, info, page, settings)
  File "/home/moose/python/MooseDocs/extensions/appsyntax.py", line 315, in createToken
    obj = self.extension.find(settings['syntax'], page, self.NODE_TYPE)
  File "/home/moose/python/MooseDocs/extensions/appsyntax.py", line 261, in find
    raise exceptions.MooseDocsException(msg, name)
MooseDocs.common.exceptions.MooseDocsException: '/Kernels/UncoupledGrainBoundaryPhaseIndicator' syntax was not recognized.

was some object that was removed. I did not remove the stub docs / I suppose that is needed...

[mangerij]

Just delete the relevant .md files in content/source/ ?

[cticenhour]

Yes, you should delete .md files associated with the objects you are removing or have already removed.

[mangerij]

@cticenhour yeah, that was it. Thanks

MooseDocs.build (MainProcess): Total Time [36.05795645713806 sec.]

Really nice that you guys have 10 femtosecond resolution on the builds

[mangerij]

Here is an interesting error @cticenhour :

In doc/content/tutorials/magnetic_ringdown.md, I am using the line

!listing tutorial/ringdown.i
         block=Kernels
         link=False
         language=python

but this yields

[AuxKernels]
  [./mag_mag]
    type = VectorMag
    variable = mag_s
    vector_x = mag_x
    vector_y = mag_y
    vector_z = mag_z
    execute_on = 'initial timestep_end final'
    block = '1'
  [../]
[]

as an output on the tutorial html version. I checked that if I list block=AuxKernels, I get the same output. I pushed this just now if you have some time to take a look. Ideally for this and other tutorials, I don't want to list the entire Kernels block but only some objects.

[cticenhour]

@mangerij I just got into the office and will take a look in between meetings.

[mangerij]

Hi @cticenhour , I was trying to publish this just now. I have an error here when I try to deploy https://github.com/mangerij/ferret/actions/runs/4582655159/jobs/8093145150

Unfortunately, I do not see any log of the error.

Do you happen to know what is going on? I added all of the output of the doc command to the orphan branch gh-pages.

[mangerij]

@cticenhour nevermind :) It worked!

[cticenhour]

Yay! Looks great :)