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?