Skip to content

Commit 7707ea0

Browse files
nojafnojaf
authored
Merge pull request #867 from nojaf/users
Initial batch of users of FSharp.Formatting.
2 parents 5055f07 + 8347a85 commit 7707ea0

File tree

4 files changed

+299
-0
lines changed

4 files changed

+299
-0
lines changed

‎FSharp.Formatting.sln

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{312E452A-1
3333
docs\markdown.fsx = docs\markdown.fsx
3434
docs\styling.md = docs\styling.md
3535
docs\upgrade.md = docs\upgrade.md
36+
docs\users.md = docs\users.md
37+
docs\zero-to-hero.md = docs\zero-to-hero.md
3638
EndProjectSection
3739
EndProject
3840
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "templates", "templates", "{D0550510-0DCE-4B40-B4FB-091668E1C5FD}"

‎docs/content/img/github-pages-settings.png

32.7 KB
Loading

‎docs/users.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
category: Documentation
3+
categoryindex: 1
4+
index: 8
5+
---
6+
# Users of FSharp.Formatting
7+
8+
The FSharp.Formatting documentation tool is widely used within the F# community.
9+
Here is a non-exhaustive list of projects:
10+
11+
<!-- temporary -->
12+
<style>
13+
table { table-layout: fixed; }
14+
tr td { padding: 15px 0; }
15+
tr td p { margin: 0 }
16+
tr th:first-child, tr td:first-child { width: 20%; }
17+
tr th:last-child, tr td:last-child { width: 35% }
18+
</style>
19+
20+
| Project name | | Repository | Note |
21+
|-----------------------------------------------------------------------------|:--|--------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
22+
| [FSharp.Formatting](https://fsprojects.github.io/FSharp.Formatting/) | | [https://github.com/fsprojects/FSharp.Formatting/](https://github.com/fsprojects/FSharp.Formatting/) | |
23+
| [F# compiler guide](https://fsharp.github.io/fsharp-compiler-docs/) | | [https://github.com/dotnet/fsharp/](https://github.com/dotnet/fsharp/) | The documentation is generated and published from [https://github.com/fsharp/fsharp-compiler-docs](https://github.com/fsharp/fsharp-compiler-docs) |
24+
| [F# Core Library Documentation](https://fsharp.github.io/fsharp-core-docs/) | | [https://github.com/dotnet/fsharp/](https://github.com/dotnet/fsharp/) | The documentation is generated and published from [https://github.com/fsharp/fsharp-core-docs](https://github.com/fsharp/fsharp-core-docs) |
25+
| [FsLexYacc](https://fsprojects.github.io/FsLexYacc) | | [https://github.com/fsprojects/fslexYacc/](https://github.com/fsprojects/fslexYacc/) | |
26+
| [FSharp.Data](https://fsprojects.github.io/FSharp.Data/) | | [https://github.com/fsprojects/FSharp.Data/](https://github.com/fsprojects/FSharp.Data/) | |
27+
| [Plotly.NET](https://plotly.net/) | | [https://github.com/plotly/Plotly.NET](https://github.com/plotly/Plotly.NET) | |
28+
| [FSharp.Stats](https://fslab.org/FSharp.Stats/) | | [https://github.com/fslaborg/FSharp.Stats/](https://github.com/fslaborg/FSharp.Stats/) | |
29+
| [FsHttp](https://fsprojects.github.io/FsHttp/) | | [https://github.com/fsprojects/FsHttp/](https://github.com/fsprojects/FsHttp/) | |
30+
| [Fantomas](https://fsprojects.github.io/fantomas/docs/) | | [https://github.com/fsprojects/fantomas/](https://github.com/fsprojects/fantomas/) | |
31+
| [Telplin](https://nojaf.com/telplin/docs/) | | [https://github.com/nojaf/telplin/](https://github.com/nojaf/telplin/) | |
32+
| [FSharp.Data.Fred](https://github.com/nhirschey/FSharp.Data.Fred/) | | [https://github.com/nhirschey/FSharp.Data.Fred/](https://github.com/nhirschey/FSharp.Data.Fred/) | |
33+
| [N Hirschey Teaching](https://nhirschey.github.io/Teaching/) | | [https://github.com/nhirschey/Teaching](https://github.com/nhirschey/Teaching) | |
34+
| [FsUnit](https://fsprojects.github.io/FsUnit/) | | [https://github.com/fsprojects/FsUnit](https://github.com/fsprojects/FsUnit) | |
35+
| [FAKE](https://fake.build/) | | [https://github.com/fsprojects/FAKE](https://github.com/fsprojects/FAKE) | |
36+
| [FSharp.Data.GraphQL](https://fsprojects.github.io/FSharp.Data.GraphQL/) | | [https://github.com/fsprojects/FSharp.Data.GraphQL](https://github.com/fsprojects/FSharp.Data.GraphQL) | |

‎docs/zero-to-hero.md

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
---
2+
category: Documentation
3+
categoryindex: 1
4+
index: 9
5+
---
6+
# From zero to hero: deploying to GitHub Pages
7+
8+
This guide is meant for a typical setup of open-source projects on GitHub.
9+
We start from a repository without any documentation and aim to end up with a published website on [GitHub Pages](https://pages.github.com/).
10+
11+
## Install the local tool
12+
13+
If you don't have a [dotnet tool manifest](https://learn.microsoft.com/en-us/dotnet/core/tools/local-tools-how-to-use#create-a-manifest-file), you can create one using `dotnet new tool-manifest`.
14+
15+
Next, we can install [fsdocs-tool](https://www.nuget.org/packages/fsdocs-tool/) using `dotnet tool install --local fsdocs-tool`.
16+
It is recommended to install this tool as a local tool because it allows us to update to newer versions of the tool at our own pace.
17+
18+
## Create the docs folder
19+
20+
After we've installed the tool, we can run `dotnet fsdocs --help` and see the available commands.
21+
Both `build` and `watch` will generate the documentation for a solution and an input folder.
22+
The default folder for `--input` is the `./docs` folder, relative to the current working directory.
23+
24+
Typically your project will be structured like:
25+
26+
```
27+
/repository-root
28+
YourSolution.sln
29+
./docs
30+
index.md
31+
other-file.md
32+
./src
33+
./Project1/Project1.fsproj
34+
./Project2/Project2.fsproj
35+
```
36+
37+
It is recommended to have a single solution at the root. In some editors, it is more convenient to open a solution at the root, to easily manipulate any file in root repository folder.
38+
When users clone your repository locally, they cannot be confused on how they need to open the project in their IDE.
39+
40+
⚠️ Please avoid putting your solution in the `src` folder. When we open that solution, it can be more difficult to edit files in the `docs` folder, as we can sometimes only see the `src` folder.
41+
42+
That being said, let's create the `docs` folder and a first Markdown file named `index.md`.
43+
When `fsdocs` runs, it will transform this `index.md` file to `index.html`, which will be served at the root.
44+
45+
We can put `# Hello world` in the markdown file for now.
46+
47+
Having this in place, should already serve the first page when we start the `watch` command:
48+
49+
> dotnet fsdocs watch
50+
51+
Open [http://localhost:8901](http://localhost:8901) and you should see our first page!
52+
53+
🪄 You might notice that there are some images missing. You can add these in the `docs` folder in the right location.
54+
55+
## Generating API documentation
56+
57+
By default, `fsdocs` will generate API documentation for the configured `--projects`.
58+
When this flag is not specified, `fsdocs` will look for solutions or projects in the working directory.
59+
It will filter these found projects, the requirements are:
60+
61+
- Having `<OutputType>library</OutputType>`
62+
- Having a binary, so you need to build your project first before the documentation can be generated.
63+
- Not having `<IsTestProject>true</IsTestProject>`
64+
- Having `<GenerateDocumentationFile>true</GenerateDocumentationFile>`
65+
66+
🪄 If you made some changes in order to adhere to the rules, you may want to remove the `.fsdocs/cache` file.
67+
68+
## Adding the missing properties
69+
70+
After our initial `watch` run, you may have noticed that some links aren't working yet.
71+
`License`, `Releases Notes` and `Source Repository` can be provided by setting MSBuild properties.
72+
73+
You can either add these properties to a single `.fsproj` file, or more typically, add them to a [Directory.Build.props](https://learn.microsoft.com/visualstudio/msbuild/customize-by-directory) file.
74+
The simplest `Directory.Build.props` file:
75+
76+
```xml
77+
<Project>
78+
<PropertyGroup>
79+
<RepositoryUrl>https://github.com/fsprojects/FSharp.AWS.DynamoDB</RepositoryUrl>
80+
<FsDocsLicenseLink>https://github.com/fsprojects/FSharp.AWS.DynamoDB/blob/master/License.md</FsDocsLicenseLink>
81+
<FsDocsReleaseNotesLink>https://github.com/fsprojects/FSharp.AWS.DynamoDB/blob/master/RELEASE_NOTES.md</FsDocsReleaseNotesLink>
82+
<PackageProjectUrl>https://fsprojects.github.io/FSharp.AWS.DynamoDB</PackageProjectUrl>
83+
</PropertyGroup>
84+
</Project>
85+
```
86+
87+
🪄 If you don't have any release notes yet, you could consider using [Ionide.KeepAChangelog](https://github.com/ionide/KeepAChangelog).
88+
89+
Running `dotnet fsdocs watch` will now yield:
90+
91+
```
92+
root --> https://github.com/fsprojects/FSharp.AWS.DynamoDB/
93+
...
94+
fsdocs-license-link --> https://github.com/fsprojects/FSharp.AWS.DynamoDB/blob/master/License.md
95+
fsdocs-release-notes-link --> https://github.com/fsprojects/FSharp.AWS.DynamoDB/blob/master/RELEASE_NOTES.md
96+
...
97+
fsdocs-repository-link --> https://github.com/fsprojects/FSharp.AWS.DynamoDB/
98+
```
99+
100+
⚠️ Again, you might need to remove `.fsdocs/cache` in order for changes to be picked up!
101+
102+
`<PackageProjectUrl>` is actually a very important property when you run `dotnet fsdocs build`.
103+
`build` will generate static files for the targeted production environment. In our case, this will be GitHub Pages.
104+
105+
Pages will host your files from https://github.com/user/project on `https://user.github.io/project/` by default.
106+
You can change this by adding a custom domain so we need to be sure that all links and urls will be generated correctly during a build.
107+
108+
Let's now run `dotnet fsdocs build`.
109+
110+
`<PackageProjectUrl>` will replace the `{{root}}` substitution, which is used all over the place in the default template.
111+
112+
⚠️ You want to ensure that the static files in the `output` folder (after running the build) have the correct links.
113+
114+
## Ignore generated files
115+
116+
Alright, at this point we've made a lot of progress. If you are using `git` you want to add the following to your [.gitignore](https://git-scm.com/docs/gitignore) file.
117+
118+
```.ignorelang
119+
# FSharp.Formatting
120+
.fsdocs/
121+
output/
122+
tmp/
123+
```
124+
125+
## Ship it!
126+
127+
Once we are satisfied with our documentation, we want to publish it to GitHub Pages.
128+
We can use [GitHub Actions](https://github.com/features/actions) to deploy our website.
129+
130+
Deploy to Pages from GitHub Actions must be enabled in the repository settings:
131+
132+
![Enable deploy from Actions](./content/img/github-pages-settings.png)
133+
134+
The typical flow is to publish your documentation after a release or after new commits were added to the default branch.
135+
Let's create a very basic Action that will deploy our website after pushing to main:
136+
137+
Create a file `.github/workflows/docs.yml`:
138+
139+
```yml
140+
name: Docs
141+
142+
# Trigger this Action when new code is pushed to the main branch
143+
on:
144+
push:
145+
branches:
146+
- main
147+
148+
# We need some permissions to publish to Github Pages
149+
permissions:
150+
contents: write
151+
pages: write
152+
id-token: write
153+
154+
jobs:
155+
build:
156+
runs-on: ubuntu-latest
157+
steps:
158+
# Checkout the source code
159+
- uses: actions/checkout@v4
160+
# Setup dotnet, please use a global.json to ensure the right SDK is used!
161+
- name: Setup .NET
162+
uses: actions/setup-dotnet@v3
163+
# Restore the local tools
164+
- name: Restore tools
165+
run: dotnet tool restore
166+
# Build the code for the API documentation
167+
- name: Build code
168+
run: dotnet build -c Release YourSolution.sln
169+
# Generate the documentation files
170+
- name: Generate the documentation'
171+
run: dotnet fsdocs build --properties Configuration=Release
172+
# Upload the static files
173+
- name: Upload documentation
174+
uses: actions/upload-pages-artifact@v2
175+
with:
176+
path: ./output
177+
178+
# GitHub Actions recommends deploying in a separate job.
179+
deploy:
180+
runs-on: ubuntu-latest
181+
needs: build
182+
steps:
183+
- name: Deploy to GitHub Pages
184+
id: deployment
185+
uses: actions/deploy-pages@v2
186+
```
187+
188+
⚠️ Careful yaml is indentation sensitive!
189+
190+
## Next steps
191+
192+
Mission accomplished, right? If everything went well, you should have a published website at this point!
193+
Here are some next steps you could consider:
194+
195+
### Use fsx file in your documentation
196+
197+
Create documentation using [Literate Scripts](../literate.html). A typical flow here is that you load your locate project binary into a script and create examples using the latest code:
198+
199+
```fsharp
200+
#r "../src/Project1/bin/Debug/net6.0/Project1.dll"
201+
202+
open Project1
203+
204+
// Actual consumption of your project!
205+
let result = SomeType.SomeMethod("foo")
206+
```
207+
208+
When using the `--strict` flag in `dotnet fsdocs build`, your documentation generation will fail if your script contains errors.
209+
This is useful to ensure your documentation is always in sync with your latest public API!
210+
211+
### Automatically update to newer versions of fsdocs-tool
212+
213+
Using [Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates) you can easily receive new PR's with updates to your `dotnet` dependencies.
214+
215+
Create a `github/dependabot.yml` file with:
216+
217+
```yml
218+
version: 2
219+
updates:
220+
# Update to newer version of GitHub Actions
221+
- package-ecosystem: "github-actions"
222+
directory: "/"
223+
schedule:
224+
interval: "weekly"
225+
226+
# Update to newer NuGet dependencies
227+
- package-ecosystem: "nuget"
228+
directory: "/"
229+
schedule:
230+
interval: "daily"
231+
```
232+
233+
This will automatically create a new PR when there is an update to the `fsdocs` tool.
234+
235+
⚠️ P️lease be very careful, if you have followed along, we don't have any GitHub Actions right now that run against pull requests!
236+
It is recommended to have an Action that builds your documentation against any incoming changes.
237+
You typically want to lint code, run unit tests and perform other useful checks as well!
238+
239+
Example Action, `.github/workflows/ci.yml`:
240+
```yml
241+
name: CI
242+
243+
on: [pull_request]
244+
245+
jobs:
246+
build:
247+
runs-on: ubuntu-latest
248+
249+
steps:
250+
- uses: actions/checkout@v3
251+
- name: Setup .NET Core
252+
uses: actions/setup-dotnet@v3
253+
- name: Restore tools
254+
run: dotnet tool restore
255+
- name: Build
256+
run: dotnet build YourSolution.sln
257+
- name: Documentation
258+
run: dotnet fsdocs build
259+
```
260+
261+
⚠️ Also never trust any update to `fsdocs` blindly, always check the [release notes](https://github.com/fsprojects/FSharp.Formatting/blob/main/RELEASE_NOTES.md) to see if there are any breaking changes.

0 commit comments

Comments
 (0)