Merge pull request idaholab#26383 from cticenhour/moosedocs-generate

Improve MooseDocs setup instructions for new applications

conda/moose-dev/conda_build_config.yaml

@@ -5,7 +5,7 @@ moose_wasp:
   - moose-wasp 2023.11.29
 
 moose_tools:
-  - moose-tools 2023.11.28
+  - moose-tools 2023.12.20
 
 moose_peacock:
   - moose-peacock 2023.11.29

conda/moose-dev/meta.yaml

@@ -6,7 +6,7 @@
 #   framework/doc/packages_config.yml
 #
 # As well as any directions pertaining to modifying those files.
-{% set version = "2023.12.19" %}
+{% set version = "2023.12.20" %}
 
 package:
   name: moose-dev

conda/moose/conda_build_config.yaml

@@ -1,5 +1,5 @@
 moose_dev:
-  - moose-dev 2023.12.19
+  - moose-dev 2023.12.20
 
 #### Darwin SDK SYSROOT
 CONDA_BUILD_SYSROOT:                                        # [osx]

conda/tools/meta.yaml

@@ -2,8 +2,11 @@
 # REMEMBER TO UPDATE the .yaml files for the following packages:
 #   moose-dev/*
 #
+#   And documentation:
+#   framework/doc/packages_config.yml
+#
 # As well as any directions pertaining to modifying those files.
-{% set version = "2023.11.28" %}
+{% set version = "2023.12.20" %}
 
 package:
   name: moose-tools

framework/doc/packages_config.yml

@@ -6,4 +6,5 @@ minimum_python: 3.7
 mpich: 4.0.2
 petsc_alt: 3.11.4
 petsc: 3.20.1
-moose_dev: 2023.12.19
+moose_dev: 2023.12.20
+moose_tools: 2023.12.20

python/doc/content/python/MooseDocs/setup.md

@@ -1,10 +1,50 @@
-# MooseDocs Setup
+# MooseDocs Setup for MOOSE-based Applications
 
 Any MOOSE-based application can use the MooseDocs system to create custom websites. If MOOSE is
-installed then the necessary dependencies exist. Also, if you have recently created an application
-with stork (after Aug. 15, 2018) then your application will have the files for a simple website
-created. The sections below will aid in setting up your application if you do not have the
-dependencies or the necessary documentation files.
+installed, the necessary dependencies exist. Also, if you have recently created an application
+with the [stork script](https://github.com/idaholab/moose/blob/master/scripts/stork.sh) (after
+Aug. 15, 2018) then your application will have the files necessary for a simple website already.
+The sections below will aid in setting up your application if you do not have the dependencies or
+the necessary documentation files.
+
+## Create Base Documentation Files
+
+If you have an existing application without a `doc` directory, then a few files must be created
+before you can begin building a website.
+
+First, create a `doc` directory at the root of your application code that contains the homepage for
+your application.
+
+```bash
+cd ~/project/your_animal
+mkdir doc
+mkdir doc/content
+echo "# YourAnimalApp" > doc/content/index.md
+```
+
+Second, create the MooseDocs executable and configuration file. This is most easily done by copying
+the files used by the stork script.
+
+```
+cp ~/projects/moose/stork/doc/moosedocs.py.app ~/projects/your_animal/doc/moosedocs.py
+cp ~/projects/moose/stork/doc/config.yml.app ~/projects/your_animal/doc/config.yml
+```
+
+Once the files are copied over, replace all mentions of "Stork" in the `config.yml` with the name
+of your application.
+
+## Install Dependencies
+
+If you are not using [the MOOSE conda package](getting_started/installation/conda.md optional=True)
+or your package is old, then we suggest that a new `moose-tools` package be installed to obtain all
+needed dependencies, which can be done using conda. This command assumes that you have created and
+activated a conda environment for your MOOSE development:
+
+!package! code
+conda install moose-tools=__MOOSE_TOOLS__
+!package-end!
+
+## Build a Live Website
 
 To build a live website for your application, run the following:
 
@@ -20,45 +60,75 @@ need to be re-executed.
 This executable contains command-line based help, which can be accessed using the "-h" flag as
 follows.
 
-```
+```bash
 cd ~/projects/your_animal/docs
 ./moosedocs.py -h
 ```
 
 The configuration file contains information on how to build the website, additional details regarding
 this file may be found at [MooseDocs/config.md].
 
-Once you have a basic website running the next step is to document your code, it is best to refer to
-the MOOSE instructions for documentation (see [framework/documenting.md]). In general, applications
-mimic the MOOSE process.
+Once you have a basic website running, it is time to document your custom code and application
+objects. Information to get started follows in the next section of this documentation. In general,
+applications mimic the MOOSE process, so it is best to also refer to the MOOSE instructions for
+documentation (see [framework/documenting.md]).
 
-## Dependencies
+## Generating Object Documentation Files
 
-If you are not using a MOOSE package or your package is old, then the following packages must be
-installed, which can be done using [pip](https://pip.pypa.io/en/stable/).
+During the course of development, especially during the creation of new application objects (e.g., kernels,
+boundary conditions, interface conditions, etc.), it is important to create documentation outlining
+any new capabilities. Templates for object documents can be generated using the MooseDocs script
+using the "generate" sub-command. To generate templates for new objects (and assuming your application
+is named `Foo`), run:
 
-```bash
-pip install --user pybtex livereload==2.5.1 pylatexenc anytree pandas
+```
+cd ~/projects/foo
+./moosedocs.py generate app_types FooApp
 ```
 
-## Creating Documentation Files
+For example, with a new kernel object called `FooDiffusion` without documentation, the following
+output will be seen:
 
-If you have an existing application without a "doc" directory, then a few files must be created
-before you can begin building a website.
+```
+% ./moosedocs.py generate app_types FooApp
+Creating/updating stub page: /Users/username/projects/Foo/doc/content/source/kernels/FooDiffusion.md
+CRITICAL:0 ERROR:0 WARNING:0
+```
 
-First create a doc directory that contains the homepage for your application.
+And the following template would be created:
 
-```bash
-cd ~/project/your_animal
-mkdir doc
-mkdir doc/content
-echo "# YourAnimalApp" > doc/content/index.md
-```
+```markdown
+# FooDiffusion
 
-Second, create the MooseDocs executable and configuration file. This is done by copying the files
-used by the stork script.
+!alert construction title=Undocumented Class
+The FooDiffusion has not been documented. The content listed below should be used as a starting point for
+documenting the class, which includes the typical automatic documentation associated with a
+MooseObject; however, what is contained is ultimately determined by what is necessary to make the
+documentation clear for users.
 
+!syntax description /Kernels/FooDiffusion
+
+## Overview
+
+!! Replace these lines with information regarding the FooDiffusion object.
+
+## Example Input File Syntax
+
+!! Describe and include an example of how to use the FooDiffusion object.
+
+!syntax parameters /Kernels/FooDiffusion
+
+!syntax inputs /Kernels/FooDiffusion
+
+!syntax children /Kernels/FooDiffusion
 ```
-cp ~/projects/moose/stork/doc/moosedocs.py ~/projects/your_animal/doc
-cp ~/projects/moose/stork/doc/config.yml ~/projects/your_animal/doc
-```
+
+Note that certain items, such as the source code description, object parameters, inputs in which the
+object is used, and child objects are filled in automatically using the [MooseDocs/extensions/appsyntax.md].
+The lines leading with `!!` as well as the `!alert` extension command should be removed and replaced
+with relevant documentation regarding how to use the object.
+
+!alert! note title=Use good documentation practices!
+When creating documentation, it is particularly important to note any design limitations or assumptions
+as well as best practices to apply when using the object.
+!alert-end!

scripts/tests/versioner_hashes.yaml

@@ -183,3 +183,9 @@ a2e8814e28b97171ff4a06e5343063fed6763dd0: #26102
   libmesh: bad5b94
   moose-dev: 2cdf24d
   wasp: 91987a3
+d5ed287fadcea6167a6c9d75924f1c11007ab51d: #26383
+  mpich: 702900f
+  petsc: 684d2af
+  libmesh: bad5b94
+  moose-dev: f8a2f21
+  wasp: 91987a3