Docgen
This MR adds logic to generate a complete HTML README for PyARC.
@nstauff please conduct official technical review and branch merge.
Merge request reports
Activity
mentioned in commit 8b66b1ac
@lefebvre thanks for developing the documentation generation capability. I did my review and merged the two branches. However, I notice that I cannot currently run the docgen script as I am missing some files:
./docgen.sh: line 22: ./..//bin/docprint: No such file or directory
Do I need to install something to be able to run the script? Thanks!@nstauff, yes, the docprint is the new WASP util. You can build it from the latest code.ornl.gov/neams-workbench/wasp or run the attached installer wasp-installer.zip
- unzip wasp-installer.zip
- run
./WASP-0.1.1-Darwin.sh --skip-license --prefix=/PATH/TO/PyARC
- run
/PATH/TO/PyARC/bin/docprint /PATH/TO/PyARC/etc/arc.sch > arc.html
- open arc.html
- enjoy
Let me know if you run into any issues.
Thanks @lefebvre . So I am running into a few issues:
On .2):
c355241:wasp-installer nstauff$ ./WASP-0.1.1-Darwin.sh --skip-license --prefix=/Users/nstauff/PyARC WASP Installer Version: 0.1.1, Copyright (c) Humanity This is a self-extracting archive. The archive will be extracted to: /Users/nstauff/PyARC Using target directory: /Users/nstauff/PyARC Extracting, please wait... pax: length of string from extended header bigger than header field: THAT won't work! pax: length of string from extended header bigger than header field: THAT won't work! pax: length of string from extended header bigger than header field: THAT won't work! pax: length of string from extended header bigger than header field: THAT won't work! ... Unpacking finished successfully
On .3):
c355241:wasp-installer nstauff$ run /Users/nstauff/PyARC/bin/docprint /Users/nstauff/PyARC/etc/arc.sch > arc.html -bash: run: command not found c355241:wasp-installer nstauff$ /Users/nstauff/PyARC/bin/docprint /Users/nstauff/PyARC/etc/arc.sch > arc.html
On .4), I got something pretty awful. I imagine, this is because 2.) failed and 3) wasn't executed properly...
### Table Of Contents - [root](#root_anchor) - [arc](#arc) - [geometry](#arcgeometry) - [materials](#arcgeometrymaterials) - [blends](#arcgeometryblends) - [surfaces](#arcgeometrysurfaces) - [reactor](#arcgeometryreactor) - [calculations](#arccalculations) - [mcc3](#arccalculationsmcc3) - [dif3d](#arccalculationsdif3d) - [lumped_element_external_list](#lumped_element_external_list) - [afrac](#lumped_element_external_listafrac) - [Referenced Choice Lists](#refchoicelists) --- ### [/](#root_anchor) Name|Type|HowMany|ValueType|Restrictions|Description :---:|:---:|:---:|:---:|:---:|:---:| [arc](#arc)|SubObject|0 or 1|||Input definition for ARC codes| [lumped_element_external_list](#lumped_element_external_list)|SubObject|0 or 1|||Description of a list of isotopes in a new lumped element| --- ### [/](#root_anchor)[arc](#arc) #### Input definition for ARC codes ##### How Many: 0 or 1 Name|Type|HowMany|ValueType|Restrictions|Description :---:|:---:|:---:|:---:|:---:|:---:| [geometry](#arcgeometry)|SubObject|1|||[required] Description of the core model| [calculations](#arccalculations)|SubObject|0 or 1|||Description of the list of calculations| --- ### [/](#root_anchor)[arc](#arc)/[geometry](#arcgeometry) #### [required] Description of the core model ##### How Many: 1 Name|Type|HowMany|ValueType|Restrictions|Description :---:|:---:|:---:|:---:|:---:|:---:| [materials](#arcgeometrymaterials)|SubObject|1|||[required] List of materials| [blends](#arcgeometryblends)|SubObject|0 or 1|||List of mixtures of materials| [surfaces](#arcgeometrysurfaces)|SubObject|1|||[required] List of surfaces used for geometry description| [reactor](#arcgeometryreactor)|SubObject|0 or 1|||[required] Description of the core with lattice of assemblies| --- ### [/](#root_anchor)[arc](#arc)/[geometry](#arcgeometry)/[materials](#arcgeometrymaterials) #### [required] List of materials ##### How Many: 1 Name|Type|HowMany|ValueType|Restrictions|Description :---:|:---:|:---:|:---:|:---:|:---:| [material](#arcgeometrymaterialsmaterial)|SubObject|1 or more|||[required] Material definition| --- ### [/](#root_anchor)[arc](#arc)/[geometry](#arcgeometry)/[materials](#arcgeometrymaterials)/[material](#arcgeometrymaterialsmaterial) #### [required] Material definition ##### How Many: 1 or more Name|Type|HowMany|ValueType|Restrictions|Description :---:|:---:|:---:|:---:|:---:|:---:| id|Tag|1|String||| wdensity|KeyedValue|0 or 1|Real|__Range__ \[0.0,+INF\)|Weight density of material [g/cm3]| adensity|KeyedValue|0 or 1|Real|__Range__ \[0.0,+INF\)|Atom density of material [at/barn-cm]| temp|KeyedValue|1|Real|__Range__ \[0.0,+INF\)|[required] Temperature [Kelvin]| [wfracs](#arcgeometrymaterialsmaterialwfracs)|SubObject|0 or 1|||Isotopic composition defined as weight fractions| [adens](#arcgeometrymaterialsmaterialadens)|SubObject|0 or 1|||Isotopic composition defined as atom densities| [afracs](#arcgeometrymaterialsmaterialafracs)|SubObject|0 or 1|||Isotopic composition defined as atom fractions| [wdens](#arcgeometrymaterialsmaterialwdens)|SubObject|0 or 1|||Isotopic composition defined as weight densities| [aform](#arcgeometrymaterialsmaterialaform)|SubObject|0 or more|||Isotopic composition defined as atom formulas| [lumped_element_aden](#arcgeometrymaterialsmateriallumped_element_aden)|TaggedValue|0 or more|||Atom density of lumped element specified in calculations/mcc3| --- ### [/](#root_anchor)[arc](#arc)/[geometry](#arcgeometry)/[materials](#arcgeometrymaterials)/[material](#arcgeometrymaterialsmaterial)/[wfracs](#arcgeometrymaterialsmaterialwfracs) #### Isotopic composition defined as weight fractions ##### How Many: 0 or 1 Name|Type|HowMany|ValueType|Restrictions|Description :---:|:---:|:---:|:---:|:---:|:---:| [wfrac](#arcgeometrymaterialsmaterialwfracswfrac)|TaggedValue|1 or more|||| --- ### [/](#root_anchor)[arc](#arc)/[geometry](#arcgeometry)/[materials](#arcgeometrymaterials)/[material](#arcgeometrymaterialsmaterial)/[wfracs](#arcgeometrymaterialsmaterialwfracs)/[wfrac](#arcgeometrymaterialsmaterialwfracswfrac) ##### How Many: 1 or more Name|Type|HowMany|ValueType|Restrictions|Description :---:|:---:|:---:|:---:|:---:|:---:| id|Tag|1|String|__Choices__ REF:[CompNames](#ref-compnames) ...
@nstauff,2 completed successfully, the message is unfortunate, but harmless (at least as I have observed to date).
3 was run successfully, the literal 'run' isn't needed, your second command is correct... but it generates HTML, which is an XML language, so in plain text it looks pretty awful.
Could you upload the arc.html file? The snippet you have doesn't look like html.
You need to open the HTML using an internet browser.
Via the command line you can do this using the
open
command which will use your default browser for html files:open arc.html
arc.html Attached is the arc.html generated. even when I open it with Safari it looks awful.
One question I had is will I be able to run the docgen.sh script you pushed in PyARC/scripts ? This would allow to concatenate the arc.html into my README files.
Thanks!
OK, thanks! I still have a crash: it is not finding the
pandoc
command. Reading WASP doc, it seems I have to download it. Correct?c355241:scripts nstauff$ ./docgen.sh #!/bin/bash -evx SOURCE=`dirname $0`/../ dirname $0 ++ dirname ./docgen.sh + SOURCE=./../ MD_TARGET=PyARC_README.md + MD_TARGET=PyARC_README.md # # create complete document # # 0. Start with GitLab-flavored style cat $SOURCE/scripts/gitlab_style.txt > $MD_TARGET + cat ./..//scripts/gitlab_style.txt # 1. Add root readme cat $SOURCE/README.md >> $MD_TARGET + cat ./..//README.md # 2. Add tests readme cat $SOURCE/test/README.md >> $MD_TARGET + cat ./..//test/README.md # 3. Add etc/InputDefinition readme cat $SOURCE/etc/README.md >> $MD_TARGET + cat ./..//etc/README.md # 4. Add auto generated schema readme $SOURCE/bin/docprint $SOURCE/etc/arc.sch >> $MD_TARGET + ./..//bin/docprint ./..//etc/arc.sch # 5. Convert inter-readme-anchor links to intra # i.e., [schema](etc/README.md#schema) -> [schema](#schema) sed -i '' 's@\](/[^\#]*\#@\](\#@g' $MD_TARGET + sed -i '' 's@\](/[^\#]*\#@\](\#@g' PyARC_README.md # 6. Convert document links to be README-relative # i.e., [PyARC](/PyARC.py) -> [PyARC](./PyARC.py) sed -i '' 's@\](/@\](./@g' $MD_TARGET + sed -i '' 's@\](/@\](./@g' PyARC_README.md # Convert complete Markdown readme to HTML pandoc $MD_TARGET -o PyARC_README.html + pandoc PyARC_README.md -o PyARC_README.html ./docgen.sh: line 34: pandoc: command not found