jan0660 / docfxmarkdowngen

Docusaurus Markdown generator using DocFX.

Jan0660

Hello there, I'm Jan!

Here I develop the RCaron(ř) programming language and the JanD process manager. I also make and maintain a few libraries: Log73 and AzurAPI/AzurAPINet.

Click for GitHub stats

docfxmarkdowngen's Issues

NullReferenceException when parsing Global.yml

v0.3.0
Hit the following exception:

[INFO] DocFxMarkdownGen v0.3.0 running...
[INFO] Read all YAML in 12ms.
[INFO] Generating and writing markdown...
Unhandled exception. System.NullReferenceException: Object reference not set to an instance of an object.
   at Program.<>c__DisplayClass0_0.<<<Main>$>b__15>d.MoveNext() in /home/runner/work/DocFxMarkdownGen/DocFxMarkdownGen/Program.cs:line 210
--- End of stack trace from previous location ---
   at System.Threading.Tasks.Parallel.<>c__50`1.<<ForEachAsync>b__50_0>d.MoveNext()
--- End of stack trace from previous location ---
   at Program.<Main>$(String[] args) in /home/runner/work/DocFxMarkdownGen/DocFxMarkdownGen/Program.cs:line 208
   at Program.<Main>(String[] args)

when parsing the Docfx generated Global.yml:

### YamlMime:ManagedReference
items:
- uid: Global
  id: Global
  children:
  - Global.UpdateTest
  - Global.VertexGrid
  langs:
  - csharp
  - vb
  name: ''
  nameWithType: ''
  fullName: ''
  type: Namespace
  assemblies:
  - TextReveal.Runtime
references:
- uid: Global.VertexGrid
  commentId: T:Global.VertexGrid
  name: VertexGrid
  nameWithType: VertexGrid
  fullName: VertexGrid
- uid: Global.UpdateTest
  commentId: T:Global.UpdateTest
  name: UpdateTest
  nameWithType: UpdateTest
  fullName: UpdateTest

Issue during running

Hi what could be causing this error? It starts to run and a few md scripts are made

[INFO] DocFxMarkdownGen v0.1.5 running...
[INFO] Read all YAML in 66ms.
[INFO] Generating and writing markdown...
Unhandled exception. System.NullReferenceException: Object reference not set to an instance of an object.
   at Program.<<Main>$>g__SourceLink|0_10(Item item) in C:\Users\Jan\RiderProjects\DocFxMarkdownGen\Program.cs:line 132
   at Program.<<Main>$>g__Declaration|0_11(StringBuilder str, Item item) in C:\Users\Jan\RiderProjects\DocFxMarkdownGen\Program.cs:line 136
   at Program.<>c__DisplayClass0_0.<<<Main>$>b__12>d.MoveNext() in C:\Users\Jan\RiderProjects\DocFxMarkdownGen\Program.cs:line 161
--- End of stack trace from previous location ---
   at System.Threading.Tasks.Parallel.<>c__50`1.<<ForEachAsync>b__50_0>d.MoveNext()
--- End of stack trace from previous location ---
   at Program.<Main>$(String[] args) in C:\Users\Jan\RiderProjects\DocFxMarkdownGen\Program.cs:line 145
   at Program.<Main>(String[] args)
zsh: abort      dfmg

include exceptions

Broken Links when trying to build Docusaurus

v 0.3.1

Hit the following exception while trying to build Docusaurus

Error: Broken links found!

- On source page path = /dev/Framework/Framework.Infrastructure.AspNetCore.Logging/:
   -> linking to ../Serilog/Serilog (resolved as: /dev/Framework/Serilog/Serilog) 
//Docusaurus only knows about /dev/Framework/Serilog as the file gets used as index

When I try to update to 0.4.0 I get the same error for all pages

- On source page path = /dev/Framework/Framework.Infrastructure.Cosmos/CosmosHelper:
   -> linking to /dev/framework

- On source page path = /dev/Framework/Framework.Infrastructure.Cosmos/MigrationApplication`TContext`:
   -> linking to /dev/framework

- On source page path = /dev/Framework/Framework.Infrastructure.Cosmos/TestHelper:
   -> linking to /dev/framework

- On source page path = /dev/Framework/Framework.Infrastructure.Cronjob.Crontab/:
   -> linking to /dev/framework
   
   // and so on...

fix for modern Docusaurus

The selected Index in the below screenshot should be the namespace name and the Index below should be at the top.

Add newline <br /> linebreak support

I've noticed that ther is a mismatch between how newline is handled between docfx and docusaurus.

original class comment:

<summary>
list of features:
1) something
2) nice
</summary>

In docfx HTML (displays correct newlines):

list of features:
1) something
2) nice

In Docusaurus (displays as though they're all one paragraph):
list of features: 1) something 2) nice

I guess when authoring markdown for Docusaurus they expect you to be explicit about your linebreaks. That's fine, but in API documentation you typically don't need to do this..Perhaps there is an opportunity for DFMG to add "
" to the end of newlines to make it display as intended in Docusaurus?

Full recommended tags support

From https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags.

• General Tags used for multiple elements - These tags are the minimum set for any API.
  • <summary>: The value of this element is displayed in IntelliSense in Visual Studio.
  • <remarks>: Tags used for members - These tags are used when documenting methods and properties.
  • <returns>
  • <param>
  • <paramref>
  • <exception>
• Format documentation output - These tags provide formatting directions for tools that generate documentation.
  • <para>
  • <list>
  • <c>
  • <code>
  • #7
  • <inheritdoc> (should be handled by docfx itself)
  • <include>
• Generate links and references - These tags generate links to other documentation.
  • <see>
  • <seealso>
  • cref
  • href - maybe already is?
• Tags for generic types and methods - These tags are used only on generic types and methods
  • <typeparam>
  • <typeparamref>

the compiler and Visual Studio validate the <b>, <i>, <u>, <br/>, and <a> tags.

• <b>
• <i>
• <u>
• <br/> (also support <br /> with the space just to be sure)
• <a>

handle <code> in xml doc

Currently looks like this:

Add option to group types (classes/enums etc)

Super handy tool!

This one is probably out of scope but I thought I'd ask..

It would be a really useful to have an option to generate grouping (folders) for different types. This way all of the classes would be together and all of the enums would be together.

Include examples