Documentation formatting

[ForNeVeR]

Currently the main documentation page looks pretty bizzare:

I think that maybe you need to leave an empty line before every list, and they will render correctly then (that initial problem was fixed by #202).

Another errors I've found:

• Querying link doesn't look like a link:

  

• Some of the core documentation pages differ from the main page in their design (just like they used an old template version)
• all the links in that old template navigation block are broken. Go to General page and try to click any navigation link
• Constraints & Relationships page looks very strange (as if it wasn't formatted at all); the same for SQL Server and SQLite
• CRUD page, Programmability, Individuals,Composable and ODBC pages are not found (returns 404) although I can see their sources in the project
• License link from the navigation block is not working

:warning: When I've tried to build the documentation using ./build.cmd GenerateHelp, it threw an exception (see here). Maybe that's the core reason all these pages weren't generated or were generated with defects.

[pezipink]

I know, we changed a ton of the docs and structure, this is the first time it has been published and several things are broken with it. I am getting to it :) thanks

[ForNeVeR]

I'd be happy to help, but haven't still found a way to build a documentation.

[ForNeVeR]

...so please note that a link to license is also broken: it leads to https://github.com/fsprojects/SQLProvider/blob/master/LICENSE.md while it should point to https://github.com/fsprojects/SQLProvider/blob/master/LICENSE.txt

[pezipink]

it is all generated from the markdown and f# formatting files in this directory

https://github.com/fsprojects/SQLProvider/tree/master/docs

if you do a release build from FAKE it will generate all the docs as well, you should be able to view them like a web page from the build output (I think, I have not done it for a long time and I have some local problems with my docs I haven't sorted out from a long time back).

Any help would be much appreciated! :+1:

[ForNeVeR]

I've tried to execute .\packages\FAKE\tools\FAKE.exe BuildDocs, but it generated only API reference (at docs/output/reference) and nothing else. It haven't prepared that main page from index.fsx, for example.

How could I achieve that? I've also tried FAKE ReleaseDocs (per ProjectScaffold documentation) and also FAKE Release, but it seems to just copy the same files to /temp and trying to push them to GitHub (i.e. "release" them).

I think there should be a bit more documentation on how to generate the documentation, guys :)

[pezipink]

not sure without trying myself which I cannot do at the moment @colinbull ?

[pezipink]

it should be running this ? (which might need some changes) https://github.com/fsprojects/SQLProvider/blob/master/docs/tools/generate.fsx

[ForNeVeR]

Thanks for the clue, I think that's the target GenerateHelp does. While executing that, I got IndexOutOfRangeException :laughing:

> .\packages\FAKE\tools\FAKE.exe GenerateHelp
Building project with version: LocalBuild
Shortened DependencyGraph for Target GenerateHelp:
<== GenerateHelp

The resulting target order is:
 - GenerateHelp
Starting Target: GenerateHelp
T:\Temp\SQLProvider\docs\content\release-notes.md does not exist.
T:\Temp\SQLProvider\docs\content\license.md does not exist.
FSharp.Formatting Information: 0 : FSharp.Formatting Logging setup!
Yaaf.FSharp.Scriping Information: 0 : Yaaf.FSharp.Scripting Logging setup!
Copying file: T:\Temp\SQLProvider\docs\output\dummy.txt
Copying file: T:\Temp\SQLProvider\docs\output\sqlite\northwindEF.db
Copying file: T:\Temp\SQLProvider\docs\output\sqlite\System.Data.SQLite.dll
Copying file: T:\Temp\SQLProvider\docs\output\sqlite\System.Data.SQLite.Linq.dll
Copying file: T:\Temp\SQLProvider\docs\output\msaccess\Northwind.accdb
Copying file: T:\Temp\SQLProvider\docs\output\msaccess\Northwind.MDB
Copying styles and scripts: T:\Temp\SQLProvider\docs\output\content\style.css
Copying styles and scripts: T:\Temp\SQLProvider\docs\output\content\style_light.css
Copying styles and scripts: T:\Temp\SQLProvider\docs\output\content\tips.js
Copying styles and scripts: T:\Temp\SQLProvider\docs\output\content\img\github-blue.png
Copying styles and scripts: T:\Temp\SQLProvider\docs\output\content\img\github.png
Generating 'T:\Temp\SQLProvider\docs\tools\..\content/index.html'
Generating 'T:\Temp\SQLProvider\docs\tools\..\content/license.html'
Generating 'T:\Temp\SQLProvider\docs\tools\..\content/release-notes.html'
Generating 'T:\Temp\SQLProvider\docs\tools\..\content\core/composable.html'
System.IndexOutOfRangeException: Индекс находился вне границ массива.
   в FSharp.CodeFormat.CodeFormatAgent.ParseSource(String file, String source, FSharpOption`1 options, FSharpOption`1 defines) в C:\PROJ\FSharp.Formatting\src\FSharp.CodeFormat\CodeFormatAgent.fs:строка 387
   в FSharp.Literate.ParseScript.parseScriptFile(String file, String content, CompilerContext ctx) в C:\PROJ\FSharp.Formatting\src\FSharp.Literate\ParseScript.fs:строка 198
   в FSharp.Literate.Literate.ParseScriptFile[d](String path, FSharpOption`1 formatAgent, FSharpOption`1 compilerOptions, FSharpOption`1 definedSymbols, FSharpOption`1 references, FSharpOption`1 fsiEvaluator) в C:\PROJ\FSharp.Formatting\src\FSharp.Literate\Main.fs:строка 67
   в FSharp.Literate.Literate.ProcessScriptFile(String input, FSharpOption`1 templateFile, FSharpOption`1 output, FSharpOption`1 format, FSharpOption`1 formatAgent, FSharpOption`1 prefix, FSharpOption`1 compilerOptions, FSharpOption`1 lineNumbers, FSharpOption`1 references, FSharpOption`1 fsiEvaluator, FSharpOption`1 replacements, FSharpOption`1 includeSource, FSharpOption`1 layoutRoots, FSharpOption`1 generateAnchors, FSharpOption`1 assemblyReferences, FSharpOption`1 customizeDocument) в C:\PROJ\FSharp.Formatting\src\FSharp.Literate\Main.fs:строка 167
   в <StartupCode$FSharp-Literate>.$Main.processScriptFile@184.Invoke(String file, String output) в C:\PROJ\FSharp.Formatting\src\FSharp.Literate\Main.fs:строка 184
   в <StartupCode$FSharp-Literate>.$Main.processDirectory@199(FSharpOption`1 format, Boolean processRecursive, FSharpFunc`2 processScriptFile, FSharpFunc`2 processMarkdown, String indir, String outdir) в C:\PROJ\FSharp.Formatting\src\FSharp.Literate\Main.fs:строка 218
   в <StartupCode$FSharp-Literate>.$Main.processDirectory@199(FSharpOption`1 format, Boolean processRecursive, FSharpFunc`2 processScriptFile, FSharpFunc`2 processMarkdown, String indir, String outdir) в C:\PROJ\FSharp.Formatting\src\FSharp.Literate\Main.fs:строка 222
   в FSharp.Literate.Literate.ProcessDirectory(String inputDirectory, FSharpOption`1 templateFile, FSharpOption`1 outputDirectory, FSharpOption`1 format, FSharpOption`1 formatAgent, FSharpOption`1 prefix, FSharpOption`1 compilerOptions, FSharpOption`1 lineNumbers, FSharpOption`1 references, FSharpOption`1 fsiEvaluator, FSharpOption`1 replacements, FSharpOption`1 includeSource, FSharpOption`1 layoutRoots, FSharpOption`1 generateAnchors, FSharpOption`1 assemblyReferences, FSharpOption`1 processRecursive, FSharpOption`1 customizeDocument) в C:\PROJ\FSharp.Formatting\src\FSharp.Literate\Main.fs:строка 181
   в FSI_0003.buildDocumentation() в T:\Temp\SQLProvider\docs\tools\generate.fsx:строка 85
   в <StartupCode$FSI_0003>.$FSI_0003.main@() в T:\Temp\SQLProvider\docs\tools\generate.fsx:строка 95
Stopped due to error
Running build failed.
Error:
System.Exception: generating help documentation failed
   в FSI_0001.Build.generateHelp'(Boolean fail, Boolean debug)
   в FSI_0001.Build.clo@157-12.Invoke(Unit _arg1)
   в Fake.TargetHelper.runSingleTarget(TargetTemplate`1 target) в C:\code\fake\src\app\FakeLib\TargetHelper.fs:строка 483

---------------------------------------------------------------------
Build Time Report
---------------------------------------------------------------------
No target was successfully completed
---------------------------------------------------------------------

(Sorry for small amounts of the Russian text in the stack trace, .NET Framework exception localization sucks a lot and I cannot turn it off easily.)

Oh that wonderful adventures in the world of building F# projects :)

[ForNeVeR]

And here's a good news: after that exception I got the documentation in the output directory, so now I think I can make a few changes to make it better.

[ForNeVeR]

I've updated the top post to mention all the problems with the docs I've found. Also there's a PR for the main page.