ellerbach / docfx-companion-tools Goto Github PK

.NET 8 has been released very recently and it is obvious but .NET 7 why not?

Everything that manages our pipeline targets .NET 7 and just for this tool I have to install the .NET 6 runtime.

Would you accept a PR that targets .NET 7 (and .NET 8 if you want)?

Thanks!

The error:

You must install or update .NET to run this application.

App: /home/ci/.dotnet/tools/DocLinkChecker
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '6.0.0' (x64)
.NET location: /home/ci/data/agent/_work/_tool/dotnet

The following frameworks were found:
  7.0.14 at [/home/ci/data/agent/_work/_tool/dotnet/shared/Microsoft.NETCore.App]

Great utility. It would be great if it could recursively traverse subfolders of the specified directory looking for markdown and .attachments in each folder found. In our DocFx, we put documentation for each component into their own folders, each also has it's own attachments folder. It's possible to script repeated calls but would be great to have it built in.

I am trying to integrate doclinkchecker and I am getting this error

./platform/Admin/Action-Hub/BuildAnAction.md 54:1
***ERROR Not found: ~/.attachments/image-ac695c92-679c-4bb6-9ce8-f02e64d6308e.png

Now the problem is that the file is there. Its even visible when I publish the generated website.

I am just not sure how to troubleshoot this. I saw #12 brought support for ~

Given this directory structure:

• A
  • B.md
• index.md

Running DocFxTocGenerator.exe --docfolder DocFxIndex --index, the toc.yml contains:

items:
- name: DocFxIndex
  href: index.md
- name: A
  href: A/B.md # links to B.md instead of index.md
  items:
  - name: A
    href: A/index.md # generated
  - name: B
    href: A/B.md

Issue 1:

The root-level item "A" links to A/B.md, because at generation-time the A/index.md didn't exist yet.

Running the TOC generator a second time fixes that:

items:
- name: DocFxIndex
  href: index.md
- name: A
  href: A/index.md # now links to A/index.md
  items:
  - name: A
    href: A/index.md # there's A/index.md again!
  - name: B
    href: A/B.md

Issue 2:

Now the TOC contains "A/index.md" twice, resulting in weird nesting in the menu, mentioning "A" twice:

Expectations

I would expect:

• The index.md generation to be done depth-first, so the index.md can be added as the directory link instead of the next first file found (in other words, that the TOC generation with --index is stable).
• An item with children that links to an index.md not to contain the index.md as item again.

So:

items:
- name: DocFxIndex
  href: index.md
- name: A
  href: A/index.md # immediately links to the generated index
  items:
  # doesn't mention it again as child item
  - name: B
    href: A/B.md

In the screenshot attached, if there is a child folder that is basically contains no direct child .md files but has child folders that contain .md files it appears that those children are completely omitted from processing. Also, I noticed that in this scenario if you attempt the multitoc generation option the tool crashes with an exception.

When generating toc's with the following params:

 -s -r -m 1 -g -v -i

The TOC's that get generated will contain duplicate entries for a folders index.md

With the following folder structure:

> docs
    - index.md
    > manual
         - index.md
         > folderA
             - index.md
             - example1.md
             - example2.md
         > folderB
             - index.md
             - example.md

I get the following toc.yml in the manual folder:

items:
- name: Manual
 href: index.md
- name: FolderA
 href: FolderA/index.md
 items:
 - name: FolderA                <------ POINTLESS!
   href: FolderA/index.md       <------ POINTLESS!
 - name: Example 1
   href: FolderA/example1.md
 - name: Example 2
   href: FolderA/example2.md
- name: FolderB
 href: FolderB/index.md
 items:
 - name: FolderB
   href: FolderB/index.md
 - name: Example
   href: FolderB/example.md

When I build this the problem becomes more obvious. Index files are essentially listed twice. Once as the "foldout" then again as an item inside the foldout:

If I delete the duplicate items in the toc.yml's and re-build it all works correctly:

See https://megalinter.io/latest/plugins/
Megalinter allows to create plugin. This can be a nice and convenient way to get the tools integrated in a larger linter infrastructure.

In the [!NOTE] tag a space get's inserted right after the exclamation mark.
[!NOTE] becomes [! NOTE]

We use this extension to generate toc.yml for Python documentation using Sphinx. In this case, we want the toc titles to be exactly the same as that of the filename.
This feature request is to add a configuration option to skip automatic title casing for toc titles.

We could generate an .override file but the feature I propose is more efficient.

Hello,

I don't understand why the index.md files are ignored by TocDocFxCreation and don't appear in the toc file ?

Regards,

Jonathan

I added a Linux tab and a Windows tab to a sample page using the example from the DocFX documentation below.

https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet#tabs

When running DocLinkChecker against this page, I receive the following two warnings.

DocLinkChecker version 1.18.0
***WARNING Heading 'tab/linux' not found in 'D:\a\docfx\docfx\docs\guides\index.md'

***WARNING Heading 'tab/windows' not found in 'D:\a\docfx\docfx\docs\guides\index.md'

Can DocLinkChecker be updated to ignore the links associated with Tabs?

Please add DocLinkChecker support for using the ~ character to represent relative paths from the root of a DocFX project.

This is essential for deeper project structures that utilize the .attachments folder at the root of a project.

This behavior is also officially supported by DocFX, but results in a failure using the companion tool suite:

Not found: ~/.attachments/abc.png

From the DocFX Tutorial page on Links and Cross References:

Sometimes you may find it's complicated to calculate relative path between two files. DocFX also supports paths that start with ~ to represent a path relative to the root directory of your project (i.e., where docfx.json is located). This kind of path will also be validated and resolved during build.

When validating for orphaned resources, errors are shown as '../../../' or something similar. This is because of an error in the sequence of parameters for calculating the relative path. Need to be fixed.

Hey there, love the utilities!

I routinely hop between Windows and macOS, and noticed while there's binaries published for Windows in this repo and on Chocolatey, there's none published for macOS or on Homebrew. Currently I'm pulling the source and rebuilding against macOS instead of Windows. I was wondering if in addition to Windows binaries, if there could be consideration in publishing release artifacts for macOS and Linux going forward as well. I can help with a PR if desired.

When using a glob pattern for documentation files (e.g. src=., files = /docs//*.md), using just ResourceFolderNames doesn't work. The entire tree of src is scanned for all folders with the name assets or images, instead of in /docs//images/**" for instance. Need resources files to a list of glob patterns as well to make this work properly.

The currently solution works perfectly if just using against 1 /docs hierarchy btw.

Hi

I'm trying to install the tool using the recommended command choco install docfx-companion-tools but it fails with the following error:

Failures
 - docfx-companion-tools - docfx-companion-tools not installed. The package was not found with the source(s) listed.
 Source(s): 'https://chocolatey.org/api/v2/'
 NOTE: When you specify explicit sources, it overrides default sources.
If the package version is a prerelease and you didn't specify `--pre`,
 the package may not be found.
Please see https://docs.chocolatey.org/en-us/troubleshooting for more
 assistance.

Any ideas regarding how this can be fixed? :)

When running DocLinkChecker it appears that the checker doesn't understand or find the links if I am using a file inclusion with a Code Snippet.

These links are rendered just find by docfx however DocLinkChecker believes they are an error.

As an example, if I have the following structure:

doc/
    index.md
    docfx.json
    scripts/
        foo.cs

and foo.cs has the following content like this:

// (other content above)

// <Bravo>
foreach(var thing in list)
{
     // Do Stuff
}
// </Bravo>

I can include the entire file with:

[!code-csharp[Code](~/Scripts/foo.cs)]

But this will be detected as an error by DocLinkChecker:

[!code-csharp[Code](~/Scripts/foo.cs?name=Bravo)]