Docfx: DocFX generating filenames that are too long for Windows

[CodingBeagle]

Hey,

During the DocFX metadata command process, I have run into troubles with DocFX simply giving the generated .yml files for source code filenames that, combined with paths, are simply way too long for Windows and Windows servers to handle. The issue I have run into is when, during an automated build process, I attempt to publish the generated static website from DocFX to a Windows server the process fails complaining that the path + filename is too long.

Is there a way in which I can costumize the naming of the generated .yml files when running the metadata command of DocFX? This way I can remove namespace prefixes that I deem unnecessary for the filenames to include :) I can't seem to find anything in the existing documentation which suggests a way of doing this?

[vicancy]

No, currently there is no way to customize the output file name.
Could you provide a PathTooLong sample file name? I'd like to check if it is a common problem that people may encounter, or a corner case that we can work around, e.g. shorten the folder name...

[CodingBeagle]

Hey @vicancy ! :)

Sure. So, at the company we follow a naming convention for all projects, starting with the name of the division, then the solution name, following by specific projects within that soluation, all in dot notation. So, for example, for a solution developed by an apartment by name of "Ib.Pdb", called "CompanySolution", with a project called "IntegrationTests". This also means that all namespaces within the projects of the solution would at the _very_ least with prefixed with "Ib.Pdb.CompanySolution.SpecificProject". Now imagine, for C# solutions, that every folder within those projects also become namespaces. Suddenly, you will have .yml files generated by DocFX that are very, very long in and of themselves, without even considering the full path for it.

For a real life example of this, one of our metadata folders in the DocFX project becomes:
"Db.Cps.PaymentDispatchDate", and one of the generated .yml files within it are the likes of:
"Db.Cps.PaymentDispatchDate.Api.Services.PaymentDispatchDate.CountryPaymentDispatchDateService.yml"

Together that would be: "Db.Cps.PaymentDispatchDate/Db.Cps.PaymentDispatchDate.Api.Services.PaymentDispatchDate.CountryPaymentDispatchDateService.yml"

Which is already very long. Now when you do copying through powershell, you'd usually have some additional path to that location on top of it, which means you very quickly exceed the Windows limit of 260 characters. We are doing workarounds now in which we place the two directories that we need to copy between when publishing the generated static site in the same location to avoid long paths. However, it would be neat if we were somehow able to customize the way in which .yml files were named so that we could eventually cut some of the namespaces off in order to make them shorter :)

[jpkempkes]

This is really quite painful. We experience this issue, when the project is built on our CI

The CI Folder has 71 chars C:TeamcityBuildagent1workfa78f37e2072fedcoptano.algorithm.tunerDoc

The Namespace has namespace has 77 chars:
Optano.Algorithm.Tuner.PopulationUpdateStrategies.CovarianceMatrixAdaptation
The class name itself adds 48 chars: CovarianceMatrixAdaptationStrategyConfiguration

The resulting filename is 261 chars:
C:TeamcityBuildagent1workfa78f37e2072fedcoptano.algorithm.tunerDocapiOptano.Algorithm.Tuner.PopulationUpdateStrategies.CovarianceMatrixAdaptation.CovarianceMatrixAdaptationStrategyConfiguration.CovarianceMatrixAdaptationStrategyConfigurationBuilder.yml

I understood this just requires a simple fix:
https://stackoverflow.com/questions/5188527/how-to-deal-with-files-with-a-name-longer-than-259-characters

We'd really appreciate a fix for this. Thanks!
jp

[jpkempkes]

This might be useful for others:
https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#enable-long-paths-in-windows-10-version-1607-and-later

Thou I'd prefer to fix docfx.

Best,
jp

[CodeDuster]

We have also run into this same situation. We did what @jpkempkes suggested and that helped, however, we are now running into the name too long issue when checking in the files into TFS. Our code base is fairly large so our namespaces are longer than average in order to keep things organized. A change to DocFX would be greatly appreciated. Thanks.