From d6b46db027430b34730e469c681ad73f308623ba Mon Sep 17 00:00:00 2001 From: nhirschey Date: Fri, 17 Nov 2023 21:05:58 +0000 Subject: [PATCH] docs --- docs/apidocs.fsx | 2 +- docs/content.fsx | 2 +- docs/evaluation.fsx | 2 +- docs/literate-notebook.ipynb | 129 +++++++++++++++++++++++++++++++++++ docs/styling.md | 2 +- docs/users.md | 2 +- docs/zero-to-hero.md | 2 +- 7 files changed, 135 insertions(+), 6 deletions(-) create mode 100644 docs/literate-notebook.ipynb diff --git a/docs/apidocs.fsx b/docs/apidocs.fsx index 5c3a1eae1..c2ea469d4 100644 --- a/docs/apidocs.fsx +++ b/docs/apidocs.fsx @@ -3,7 +3,7 @@ title: Generating API Docs category: Documentation categoryindex: 1 -index: 5 +index: 6 --- *) (*** condition: prepare ***) diff --git a/docs/content.fsx b/docs/content.fsx index e04a0e735..b686c6566 100644 --- a/docs/content.fsx +++ b/docs/content.fsx @@ -2,7 +2,7 @@ --- category: Documentation categoryindex: 1 -index: 3 +index: 5 --- *) (*** condition: prepare ***) diff --git a/docs/evaluation.fsx b/docs/evaluation.fsx index 99c603def..1fe4fbb5d 100644 --- a/docs/evaluation.fsx +++ b/docs/evaluation.fsx @@ -2,7 +2,7 @@ --- category: Documentation categoryindex: 1 -index: 6 +index: 7 --- *) (*** condition: prepare ***) diff --git a/docs/literate-notebook.ipynb b/docs/literate-notebook.ipynb new file mode 100644 index 000000000..2835d748b --- /dev/null +++ b/docs/literate-notebook.ipynb @@ -0,0 +1,129 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "dotnet_repl_cellExecutionStartTime": "2023-11-17T21:04:27.922626+00:00", + "dotnet_repl_cellExecutionEndTime": "2023-11-17T21:04:27.9559602+00:00" + }, + "source": [ + "---\n", + "category: Documentation\n", + "\n", + "categoryindex: 1\n", + "\n", + "index: 4\n", + "\n", + "---\n", + "\n", + "# Literate Notebooks\n", + "\n", + "It is possible create content using [.NET interactive](https://github.com/dotnet/interactive/tree/main) polyglot notebooks as the input file. The notebooks are processed by converting the notebook to markdown and then passing the markdown through the markdown processing pipeline.\n", + "\n", + "The `fsdocs` tool uses [dotnet-repl](https://github.com/jonsequitur/dotnet-repl) to evaluate polyglot notebooks. You need this tool to evaluate notebooks using `dotnet fsdocs --eval`. It can be installed into your local tool manifest using the command `dotnet tool install dotnet-repl`.\n", + "\n", + "F# Formatting tries to faithfully reproduce a notebook's native appearance when generating documents. Notebook cell outputs are passed through unchanged to preserve the notebook's html output. The below snippet demonstrates a notebook's html output for F# records, which differs from the output you would get with literate scripts.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "dotnet_repl_cellExecutionStartTime": "2023-11-17T21:04:27.9577608+00:00", + "dotnet_repl_cellExecutionEndTime": "2023-11-17T21:04:30.3608545+00:00", + "dotnet_interactive": { + "language": "fsharp" + }, + "polyglot_notebook": { + "kernelName": "fsharp" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
{ Name = "Alf"\\n Phone = "(555) 555-5555"\\n ZipCode = "90210" }
Name
"Alf"\r\n",
+       "
Phone
"(555) 555-5555"\r\n",
+       "
ZipCode
"90210"\r\n",
+       "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "type ContactCard =\n", + " { Name: string\n", + " Phone: string\n", + " ZipCode: string }\n", + "\n", + "// Create a new record\n", + "{ Name = \"Alf\"; Phone = \"(555) 555-5555\"; ZipCode = \"90210\" }" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": ".NET (F#)", + "language": "F#", + "name": ".net-fsharp" + }, + "language_info": { + "file_extension": ".fs", + "mimetype": "text/x-fsharp", + "name": "F#", + "pygments_lexer": "fsharp", + "version": "6.0" + }, + "polyglot_notebook": { + "defaultKernelName": "fsharp", + "items": [ + { + "name": "fsharp" + } + ] + }, + "dotnet_interactive": { + "defaultKernelName": "fsharp", + "items": [ + { + "name": "fsharp" + } + ] + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} \ No newline at end of file diff --git a/docs/styling.md b/docs/styling.md index 738c71e42..d76e1f0d3 100644 --- a/docs/styling.md +++ b/docs/styling.md @@ -1,7 +1,7 @@ --- category: Documentation categoryindex: 1 -index: 7 +index: 8 --- # Customization and Styling diff --git a/docs/users.md b/docs/users.md index b43dc684e..0185298e3 100644 --- a/docs/users.md +++ b/docs/users.md @@ -1,7 +1,7 @@ --- category: Documentation categoryindex: 1 -index: 8 +index: 9 --- # Users of FSharp.Formatting diff --git a/docs/zero-to-hero.md b/docs/zero-to-hero.md index 2234a3407..aa58e9428 100644 --- a/docs/zero-to-hero.md +++ b/docs/zero-to-hero.md @@ -1,7 +1,7 @@ --- category: Documentation categoryindex: 1 -index: 9 +index: 10 --- # From zero to hero: deploying to GitHub Pages