End-User Documentation New Structure (WIP) #2336

alanlomeli · 2022-07-06T06:53:44Z

New _template file to define fantoma's custom theme
2 new style files: global-config for reusing common variables and fsdocs-custom for adding styles to custom theme
Fix favicon and sidebar icon not displating
Added proposal for a couple of documentation sections: index.md, Configuration.md, FormattingCheck.md, GettingStarted.md, GitHooks.md, IgnoreFile.md, StyleGuide.md

Please do let me know if any comments !

nojaf

Hi Alan, you are on the right track here 😊!
Please don't commit any .css file that we generate in F#.
/docs/content/fsdocs-custom.css shouldn't be there.

We will need a couple of more rounds here before we can take this in.
That is why a draft PR can be insightful we proposing big changes.
You don't want to put too much effort into these things when the expected result isn't crystal clear.

Keep it up!

nojaf · 2022-07-06T07:12:32Z

docs/.style/homepage.sass

-html, body
+@import "./global-config.sass"
+
+html, bod


html, body

nojaf · 2022-07-06T07:17:03Z

docs/_template.html

+    <link type="text/css" rel="stylesheet" href="{{root}}content/fsdocs-{{fsdocs-theme}}.css" />
+    <link type="text/css" rel="stylesheet" href="{{root}}content/fsdocs-custom.css" />
+    <script type="text/javascript" src="{{root}}content/fsdocs-tips.js"></script>
+    <!-- HTML5 shim, for IE6-8 support of HTML5 elements -->


Remove this shim, IE is finally dead.

nojaf · 2022-07-06T07:19:10Z

docs/docs/FormattingCheck.md

@@ -0,0 +1,10 @@
+---
+category: Documentation


Use category End-user documentation instead.

nojaf · 2022-07-06T07:21:01Z

docs/docs/index.md

+Fantomas follows two F# style guides: the [F# code formatting guidelines](https://docs.microsoft.com/en-us/dotnet/fsharp/style-guide/formatting) from Microsoft by default and the [G-Research F# code formatting guidelines](https://github.com/G-Research/fsharp-formatting-conventions) via various [settings](https://github.com/G-Research/fsharp-formatting-conventions/blob/master/.editorconfig).
+
+## Use cases


Remove this section, it most likely isn't up to date anymore and doesn't tell that much.

nojaf · 2022-07-06T07:21:38Z

docs/docs/index.md

+For more complex examples, please take a look at F# outputs of [20 language shootout programs](tests/languageshootout_output) and [10 CodeReview.SE source files](tests/stackexchange_output).
+
+## Why the name "Fantomas"?


I'd move that one to the FAQ page. Is surely isn't necessary to answer on the first page.

nojaf · 2022-07-06T07:35:53Z

docs/docs/GettingStarted.md

+
+The recommended way to use Fantomas is by using the [Ionide plugin](http://ionide.io/). Fantomas is integrated in [FSAutoComplete](https://github.com/fsharp/FsAutoComplete/) which is the language server used by Ionide.
+
+Alternatively, you can install the [fantomas-fmt](https://marketplace.visualstudio.com/items?itemName=paolodellepiane.fantomas-fmt) extension.


Remove the line about fantomas-fmt, this is no longer recommended.

nojaf · 2022-07-06T07:36:37Z

docs/docs/GettingStarted.md

+> dotnet new tool-manifest
+
+Install the command line tool with:
+> dotnet tool install fantomas


Add some more styling to the blockquote, they don't really stand out right now.

nojaf · 2022-07-06T07:39:55Z

docs/_template.html

+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <meta name="author" content="{{fsdocs-authors}}">
+
+    <link rel="stylesheet" id="theme_link" href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/4.6.0/materia/bootstrap.min.css">


This uses a lot of old bootstrap (probably how the default template works).
Throw this stuff out, we want to own the styling completely.

nojaf · 2022-07-06T07:49:48Z

docs/_template.html

+
+    <link rel="shortcut icon" type="image/x-icon" href="{{root}}img/favicon.ico">
+    <link type="text/css" rel="stylesheet" href="{{root}}content/navbar-{{fsdocs-navbar-position}}.css" />
+    <link type="text/css" rel="stylesheet" href="{{root}}content/fsdocs-{{fsdocs-theme}}.css" />


You are still using the default theme by using this.
Remove <link type="text/css" rel="stylesheet" href="{{root}}content/fsdocs-{{fsdocs-theme}}.css" /> and rely on your own styling.

nojaf · 2022-07-06T07:50:33Z

docs/_template.html

+<!DOCTYPE html>
+<html lang="en">
+
+<head>


Currently, the right font isn't displaying.
You will need to add

<link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link href="https://fonts.googleapis.com/css2?family=Reem+Kufi:wght@400;500;700&display=swap" rel="stylesheet">

at some point I believe.

nojaf · 2022-07-08T07:27:41Z

docs/.style/fsdocs-custom.sass

+#fsdocs-content
+
+    h1 a


Maybe write this in one selector instead of repeating yourself.
Something like:

h1, h2, h3, h4, h5, h6 a color: $black

nojaf · 2022-07-08T07:46:11Z

docs/.style/style.fsx

+            sassCompiler.CompileFile(inputFileTemplate, ?outputPath = Some outputTemplate)
+
+        let globalConfig =
+            sassCompiler.CompileFile(inputGlobalConfig, ?outputPath = Some outputGlobalConfig)


I don't think the globalConfig should be compiled since it is only imported by the other files.

nojaf · 2022-07-14T08:20:53Z

Making another note here, I think we currently have two limitations with using FsDoc.

We cannot control the menu items (Customize the menu items of {{fsdocs-list-of-documents}} and {{fsdocs-list-of-namespaces}} FSharp.Formatting#754)
We cannot control the generated HTML of the API documentation

For the first problem, I'd propose a two-folded workaround:

While developing, we add some JavaScript that transforms the existing HTML to what we need.
After the build, when all HTML files are generated, we do some post-processing to update the HTML to what we need.

This will be fixing the same thing twice but all in all, it won't be that much effort to do this.

The second problem is a lick more difficult. We will need to generate the API documentation outside of the fsdocs command line tool. This can be done using another F# script.

#r "nuget: FSharp.Formatting, 15.0.1" // Grabs a NuGet package from the NuGet Gallery.

open FSharp.Formatting.ApiDocs
open System.IO

let model =
    ApiDocs.GenerateModel(
        // These are the project dll outputs that will be used to generate the API docs.
        [ ApiDocInput.FromFile(@"C:\Users\nojaf\Projects\fantomas\src\Fantomas.FCS\bin\Debug\netstandard2.0\Fantomas.FCS.dll") 
          ApiDocInput.FromFile(@"C:\Users\nojaf\Projects\fantomas\src\Fantomas.Core\bin\Debug\netstandard2.0\Fantomas.Core.dll") ],
        collectionName = "Fantomas.Core",
        substitutions = []
    )

#r "nuget: Fable.React"

open Fable.React

// TODO: transform the model into html
// Mapping each model/namespace to its own page.

let content = div [] [
    str "hey some content"
]

open Fable.ReactServer

renderToString(content)

Using something like Fable.React (to have some sort of HTML like DSL) we can construct the HTML for the {{fsdocs-content}} placeholder.
To re-use the existing _template.html, we can write out the generated HTML as Markdown file (.md).
The HTML content will be replaced inserted in the template.

We can discuss this further during a call @yisusalanpng.

nojaf

Good initial progress @yisusalanpng!
Keep it up!

nojaf · 2022-07-15T07:35:37Z

docs/fsdocs-custom.css

@@ -0,0 +1,8198 @@
+@charset "UTF-8";


Is this generated? If so don't commit it.

to customize template

- Add new FAQ section - Changed contributors list - Cleanup template unused statements - Change section name from Documentation to End-user documentation

- Add new FAQ section - Change contributors list - Cleanup template unused statements - Change section name from Documentation to End-user documentation - Delete styleguide to build a new one - Getting Started section divided in multiple pages - Remove fantomas-fmt from recommended - Remove default stylings

- Create new benchmarks page - Add basic styling for main theme (WIP)

- Tweak fsdocs-custom.sass to add common selector for headers

- Temporal script to modify fs-docs default stylings - Add coloring styling for F# code - Add logo and searchbar for namespaces

nojaf force-pushed the documentation branch from 7dd5c8a to 302d6a4 Compare July 6, 2022 07:01

nojaf requested changes Jul 6, 2022

View reviewed changes

nojaf mentioned this pull request Jul 7, 2022

Revisit if/then/else #2334

Merged

nojaf reviewed Jul 8, 2022

View reviewed changes

nojaf marked this pull request as ready for review July 15, 2022 13:53

nojaf approved these changes Jul 15, 2022

View reviewed changes

docs/fsdocs-custom.css

@@ -0,0 +1,8198 @@

@charset "UTF-8";

Copy link

Contributor

nojaf Jul 15, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this generated? If so don't commit it.

alanlomeli and others added 16 commits July 15, 2022 16:10

End-User Documentation New Structure (WIP)

c1819e8

to customize template

Format style.fsx

f0f9bc6

Change docs name section from Documentation to End-user documentation

a5d5af4

End-User Documentation New Structure (WIP)

429911c

to customize template

Format style.fsx

902ddc0

- Reverted img folder to images

e5d19cd

- Add new FAQ section - Changed contributors list - Cleanup template unused statements - Change section name from Documentation to End-user documentation

mend

e58bad8

- Add fsharp_max_if_then_short_width to the docs

2d8b6e3

- Create new benchmarks page - Add basic styling for main theme (WIP)

- Stop compiling globalConfig

1cac4d6

- Tweak fsdocs-custom.sass to add common selector for headers

- Fix markdown section name

1c92c51

- Bootstrap sidebar

269fdfb

- Temporal script to modify fs-docs default stylings - Add coloring styling for F# code - Add logo and searchbar for namespaces

Import sidebar sass file.

d5b2e53

Add FsDocsLogoSource.

7bc6cc9

Some minor fixes.

72886fb

Format style.fsx

83960f8

nojaf force-pushed the documentation branch from 8ffafaa to 83960f8 Compare July 15, 2022 14:13

nojaf merged commit 87cd212 into fsprojects:master Jul 15, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

End-User Documentation New Structure (WIP) #2336

End-User Documentation New Structure (WIP) #2336

alanlomeli commented Jul 6, 2022

nojaf left a comment

nojaf Jul 6, 2022

nojaf Jul 6, 2022

nojaf Jul 6, 2022

nojaf Jul 6, 2022

nojaf Jul 6, 2022

nojaf Jul 6, 2022

nojaf Jul 6, 2022

nojaf Jul 6, 2022

nojaf Jul 6, 2022

nojaf Jul 6, 2022

nojaf Jul 8, 2022

nojaf Jul 8, 2022

nojaf commented Jul 14, 2022

nojaf left a comment

nojaf Jul 15, 2022

		Fantomas follows two F# style guides: the [F# code formatting guidelines](https://docs.microsoft.com/en-us/dotnet/fsharp/style-guide/formatting) from Microsoft by default and the [G-Research F# code formatting guidelines](https://github.com/G-Research/fsharp-formatting-conventions) via various [settings](https://github.com/G-Research/fsharp-formatting-conventions/blob/master/.editorconfig).

		## Use cases

		For more complex examples, please take a look at F# outputs of [20 language shootout programs](tests/languageshootout_output) and [10 CodeReview.SE source files](tests/stackexchange_output).

		## Why the name "Fantomas"?


		The recommended way to use Fantomas is by using the [Ionide plugin](http://ionide.io/). Fantomas is integrated in [FSAutoComplete](https://github.com/fsharp/FsAutoComplete/) which is the language server used by Ionide.

		Alternatively, you can install the [fantomas-fmt](https://marketplace.visualstudio.com/items?itemName=paolodellepiane.fantomas-fmt) extension.

		#fsdocs-content

		h1 a

End-User Documentation New Structure (WIP) #2336

End-User Documentation New Structure (WIP) #2336

Conversation

alanlomeli commented Jul 6, 2022

nojaf left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nojaf commented Jul 14, 2022

nojaf left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment