Open kMutagene opened 7 months ago
Allright @nojaf @nhirschey i think this is ready for a first review.
I took #875 as an opportunity to get a little familiar with the repo and how the cli tool works, so if anything is not in the correct place please correct me.
currently, the new fsdocs init
command creates this scaffold:
└───docs
│ Dockerfile
│ index.md
│ literate_sample.fsx
│ Nuget.config
│ _template.html
│ _template.ipynb
│ _template.tex
│
└───img
logo.png
i think the _template.*
files should be customizable via a flag, but would love some feedback before digging further.
Also, i included just a simple markdown and literate script file to have something there when you run fsdocs watch
, this can also serve as a starting point for creating documentation content.
As the init command must copy-paste some of the files that are also searched in the build command, i refactored that as the InRepoLocations
and InPackageLocations
classes, so those can be accessed across both commands in the same way.
Happy for any feedback
Note that this can also be easily used to init fsdocs with a custom template by also adding a fsdocs-theme.css
file (see #861 ). we could add a set of curated templates to this repo so people can choose from these e.g. via fsdocs init --theme fslab
Allright a quick summary of how i would proceed:
InNugetPackageLocations
, and adjust member names with double ticks to fully represent the locationssounds good @nojaf ?
I would like it more if there would be a way to unify InPackageLocations
and InRepoLocations
though, so it could just be DefaultLocations
determined from a base path. However i think this would need adjusting the way the templates and extras
are packaged into the nuget package, see my other comments
sounds good @nojaf ?
Yup!
Hey @nojaf, where should I put tests that check whether the location classes construct correct paths? None of the test projects seem to match the scope of testing 'Common' functions used across commands in the tool.
Hmm, this does seem like a rather new area when it comes to the existing test projects. I'm not sure really, you could create a new project I suppose. On the other hand, will this be easy to write unit tests for? Could you give an example of what you have in mind you want to test?
you could create a new project I suppose
This is what i feared, because all the existing test projects look really arcane to me - i usually just use expecto, here it seems to be FsUnit + NUnit - i can roll with that, but every test i looked at also makes heavy use of compiler directives and i have absolutely no clue on what to use from that.
Could you give an example of what you have in mind you want to test?
A really simple case would be verifying that all default paths created from a base directory are correct
Well, the whole solution is rather arcane, isn't it? Anyway, I don't think all test files are that bad.
You could also consider using https://github.com/TestableIO/System.IO.Abstractions in your implementation. That could make writing such tests easier.
oh wow, that will come in handy in other projects as well, thanks! I'll copy stuff together until i have working tests i guess ;)
This PR intends to implement a basic version of #872
additionally, i tried to refactor the way default files and folders are accessed from the build command, because the init command needs essentially the same code to copy the relevant files.