Generate NAnt documentation with Wyam

[savornicesei]

Issue by savornicesei
Wednesday Jul 22, 2020 at 16:40 GMT
Originally opened as Wyamio/Wyam#16

---

Hi @daveaglick ,

I'm trying to migrate NAnt documentation to wyam (and then to Statiq when Statiq.Docs will be stable and documented)

1. I've managed to get the nant.xsd schema file copied as-is to wyam output but it does not appear in the sidebar. I've tried several variations but I could not get it right - either it generates an html file or it does not show in the sidebar).

 Pipelines.InsertBefore(Docs.RenderPages,"XMLSchema",
    ReadFiles("release/**/*.xsd"),
    Tree().WithMetadataNames(),
    Meta(DocsKeys.ShowInSidebar, true),
    Title("XML Schema"),
    CopyFiles("release/**/*.xsd")
);
 /*
 Pipelines.InsertBefore(Docs.RenderPages,"XMLSchema",
    ReadFiles("release/**/*.xsd.md"),
    FrontMatter(Yaml()),
    Title("XML Schema"),
    WriteFiles(".xsd")
);*/
 /*
Pipelines.InsertBefore(Docs.RenderPages,"XMLSchema",
    ReadFiles("release/**.xsd"),
    Tree(),
    Meta(DocsKeys.ShowInSidebar, true),
    Title("XML Schema"),
    WriteFiles()
);
*/

2. I'm not sure how to generate the reference part of the documentation. I think the summary page(s) should look similar to Cake Add-Ins documentation but the actual documentation pages must show props and attributes in a specific order
   

3. Is it possible to use DirectoryMeta module to add metadata about the release version to all files from a release folder (e.g. /release/v0.92)? The documentation mentions some metadata document - should it be a markdown file with the needed metainfo in in in the root of the folder?
   Being able to set a Version metadata to all docs would allow me to generate correct links for that release.

You can check my work here.

Thank you for any insights you can give me (and for the awesome work on Wyam and its succesor).

All the best,
Simo

[savornicesei]

Self-answering: yes, it is possible but Wyam needs some tweaking so... fork it to Wyam2

[daveaglick]

Cool! At this point I wouldn't really know how to do very much in Wyam anyway since trying to keep it straight with Statiq would probably break my brain. So I'm glad you're able to make a go of it. When you get it working in your fork, go ahead and drop me a line so we can see what it would take to port that to Statiq for future use.

[daveaglick]

@savornicesei BTW, it looks like when copying issues to the fork it's notifying everyone who originally participated in those issues since they're included with an @. Is there a way to have your tooling omit the direct GitHub handle references when copying issues, or do you need the issues? I've been getting several questions from users about what's going on.

[savornicesei]

Hi @daveaglick
Sorry for the spam. The only way to stop the 'noise' is to ask GH to unlink the 2 repos. I'll do that.

Related to Nant documentation by Wyam:

• One blocking thing is Wyam missing some documentation tags.
  • from NAnt: note, list, listheader, list item (see AvailableTask XML comment), exception, see langword
  • from Sandcastle special XML tags: preliminary, revisionHistory, revision, permission, typeparam, threadsafety
    Since each documentation software can define new XML tags, I think the best approach is to have them customizable. At least in Wyam they're hardcoded and cannot be extended or customized their HTML output.
• There is also the need to be able to change the hyperlink name in AutoLink module
• Another thing is that Docs recipe is not extensible: existing pipelines cannot be accessed and I would like to replace that biiig wyam config script with a NAnt recipe built on top of Docs.
• On the wish list is to have a new theme for Docs based on minimal-mistakes.

I haven't figured out yet how to generate correct, relative urls everywhere but it's last on the list.

Thank you for your kind words. Please focus on Statiq - I've been waiting for more than a year for the Docs part while cutting my teeth in Wyam 😄