Skip to content
Snippets Groups Projects

Docgen

Merged Lefebvre, Robert Alexander requested to merge docgen into reorganization

This MR adds logic to generate a complete HTML README for PyARC.

@nstauff please conduct official technical review and branch merge.

Merge request reports

Pipeline #14144 failed

Pipeline failed for 575cdaaa on docgen

Approval is optional

Merged by Stauff, Nicolas EmileStauff, Nicolas Emile 6 years ago (Jul 19, 2018 5:37pm UTC)

Merge details

  • Changes merged into reorganization with 8b66b1ac.
  • Deleted the source branch.

Pipeline #14181 failed

Pipeline failed for 8b66b1ac on reorganization

Activity

Filter activity
  • Approvals
  • Assignees & reviewers
  • Comments (from bots)
  • Comments (from users)
  • Commits & branches
  • Edits
  • Labels
  • Lock status
  • Mentions
  • Merge request status
  • Tracking
  • 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

    1. unzip wasp-installer.zip
    2. run ./WASP-0.1.1-Darwin.sh --skip-license --prefix=/PATH/TO/PyARC
    3. run /PATH/TO/PyARC/bin/docprint /PATH/TO/PyARC/etc/arc.sch > arc.html
    4. open arc.html
    5. 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

  • Oh goodness... I got turned around... my apologies, docprint produces Markdown, not HTML. You have confirmed that docprint works. To generate the HTML, run the /Users/nstauff/PyARC/scripts/docgen.sh. This will generate PyARC_README.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
  • Yes, the simplest is if you have MacPorts installed you can do

    sudo port install pandoc
  • Perfect, I got it. Thanks!!

Please register or sign in to reply
Loading