Merge pull request #98 from gpproton/setup-docfx-for-axolotl

Setup docfx for axolotl

.config/dotnet-tools.json

@@ -13,6 +13,12 @@
       "commands": [
         "dotnet-ef"
       ]
+    },
+    "docfx": {
+      "version": "2.75.3",
+      "commands": [
+        "docfx"
+      ]
     }
   }
 }

.github/workflows/generate-docs.yml

@@ -0,0 +1,40 @@
+name: Generate docs with docfx
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  actions: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  publish-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Dotnet Setup
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: 8.x
+
+    - run: dotnet tool restore
+    - run: dotnet r docs:publish
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        # Upload entire repository
+        path: 'docs/_site'
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.gitignore

@@ -477,4 +477,6 @@ $RECYCLE.BIN/
 *.lnk
 .idea
 *.sqlite*
-*.db*
+*.db*
+_site
+docs/api

README.md

@@ -1,6 +1,6 @@
 # Axolotl
 
- A personal shared library for various types of dotnet project types
+A personal shared library for various types of dotnet project types
 
 NOTE: Issues can be created to improve documentation and fix errors
 

docs/docfx.json

@@ -0,0 +1,45 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "src": "../src",
+          "files": [
+            "**/*.csproj"
+          ]
+        }
+      ],
+      "dest": "api"
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "**/*.{md,yml}"
+        ],
+        "exclude": [
+          "_site/**"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "assets/**"
+        ]
+      }
+    ],
+    "output": "_site",
+    "template": [
+      "default",
+      "modern"
+    ],
+    "globalMetadata": {
+      "_appName": "Axolotl",
+      "_appTitle": "Axolotl",
+      "_enableSearch": true,
+      "pdf": true
+    }
+  }
+}

docs/getting-started.md

@@ -0,0 +1 @@
+# Getting Started

docs/index.md

@@ -0,0 +1,44 @@
+---
+_layout: landing
+---
+
+A personal shared library for various types of dotnet project types.
+
+## packages
+
+- Axolotl
+- Axolotl.Http
+- Axolotl.EFCore
+- Axolotl.Razor
+
+# Install
+
+The framework is provided as a set of NuGet packages. In many cases you'll only need the base package, but if you need efcore or razor there are implementation-specific packages available to assist.
+
+To install the run any of the following required pakage:
+
+```ps1
+Install-Package Axolotl
+Install-Package Axolotl.EFCore
+Install-Package Axolotl.AspNet
+```
+
+```csharp
+public sealed class Post : AuditableEntity<Guid> {
+    public string Title { get; set; } = null!;
+    public Category Category { get; set; } = null!;
+    public ICollection<Tag> Tags { get; set; } = null!;
+}
+```
+
+### Create your DB context
+
+```csharp
+public class ServiceContext : DbContext {
+    public ServiceContext(DbContextOptions<ServiceContext> options) : base(options) { }
+    protected override void OnModelCreating(ModelBuilder modelBuilder) { }
+
+    public virtual DbSet<Post> Posts { get; set; } = null!;
+
+}
+```

docs/toc.yml

@@ -0,0 +1,6 @@
+- name: Home
+  href: /
+- name: Getting Started
+  href: getting-started.md
+- name: API
+  href: api/

global.json

@@ -1,9 +1,11 @@
 {
   "sdk": {
-    "version": "8.0.100-preview.4.23260.5",
-    "rollForward": "latestFeature"
+    "version": "8.0.200",
+    "rollForward": "latestPatch"
   },
   "scripts": {
+    "docs": "cd docs && dotnet docfx docfx.json --serve",
+    "docs:publish": "cd docs && dotnet docfx docfx.json",
     "build": "dotnet build --configuration Release",
     "test": "dotnet test --configuration Release",
     "ci": "dotnet r build && dotnet r test",