diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml new file mode 100644 index 0000000000..5c80b9898d --- /dev/null +++ b/.github/workflows/mkdocs.yml @@ -0,0 +1,54 @@ +name: MKDocs Deploy +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' + - 'examples/**' + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Install dependencies + run: pip install mkdocs-material + + - name: Generate docs + run: dotnet run --project src/helpers/GenerateDocs/GenerateDocs.csproj . + + - name: Build with MkDocs + run: mkdocs build -d ./_site + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/docs/css/extra.css b/docs/css/extra.css new file mode 100644 index 0000000000..f2174837d6 --- /dev/null +++ b/docs/css/extra.css @@ -0,0 +1,102 @@ +/* Logo title */ +.md-header__topic:first-child { + font-weight: initial !important; +} + +/* Code font size in
*/ +details .linenos, details code { + font-size: inherit !important; +} + +/* Code block / tab in details */ +details > summary + .highlight:last-child, details > summary + .tabbed-set:last-child { margin: 0 -0.6rem !important; } +details > summary + .highlight:last-child > .highlighttable { margin: 0 !important; } + +/* Table full width */ +.md-typeset__table { display: block !important; } +.md-typeset table:not(.highlighttable) { display: table !important; } + +.md-typeset table:not([class]) th { + min-width: 0rem; +} + +.headerlink { transform: translateY(-2.5px); } + +.md-nav__link[for=__toc] .md-icon { margin-left: auto !important; } + +blockquote.page-time { + margin: 20px 0 !important; + border-left-color: #64b5f6 !important; /* Just change the color value and that's it*/ +} +blockquote.page-copyright { + margin: 20px 0 !important; + border-left-color: #ff1700 !important; /* Just change the color value and that's it*/ +} +blockquote.page-copyright i.md-icon { + display: inline-block; + margin-right: 5px; + transform: translateY(3.5px); + width: 18px; +} + +#myBtn { + display: none; + position: fixed; + bottom: 100px; + right: 16px; + z-index: 99; + border: none; + outline: none; + color: #8590a6; + cursor: pointer; + padding: .7rem; + border-radius: .4rem; +} + +#myBtn:hover { + background-color: #d3d3d3; +} + +#color-button > button { + cursor: pointer; + transition: opacity .25s; + display: inline-block; + width: 6.5rem; + margin-bottom: 0.2rem; + padding: 1.2rem 0.4rem 0.2rem; + font-size: 0.64rem; + text-align: left; +} + +#color-button > button[data-md-color-primary] { + background-color: var(--md-primary-fg-color); + color: var(--md-primary-bg-color); +} +#color-button > button[data-md-color-primary=white] { + box-shadow: inset 0 0 0.05rem rgb(0 0 0 / 54%); +} + +#color-button > button[data-md-color-accent] { + background-color: var(--md-accent-fg-color); + color: var(--md-code-bg-color); +} + +mjx-container > img { + width: 0; + height: 0; +} + +[data-md-color-scheme="slate"] { + --md-primary-fg-color: #2e303e; + --md-accent-fg-color: #00bda4; + --md-typeset-a-color: #526cfe; +} + +[data-md-color-scheme="slate"] .md-typeset img { + background: white; + filter: brightness(0.9); +} + +[data-md-color-scheme="slate"] .md-typeset img[src$=".svg"] { + border: 4px solid white; +} \ No newline at end of file diff --git a/docs/media/icon128.png b/docs/media/icon128.png new file mode 100644 index 0000000000..05d2b17ae9 Binary files /dev/null and b/docs/media/icon128.png differ diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..3797080d04 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,108 @@ +site_name: OpenAI .NET Documentation +nav: +- Overview: index.md +# EXAMPLES # + +# - Quick Start: QuickStart.md +# - Architecture: Architecture.md +# - FAQ: FAQ.md +# - Contributing Guide: ContributingGuide.md +# - Tutorials: +# - Configure the native library loading: Tutorials/NativeLibraryConfig.md +# - Use executors: Tutorials/Executors.md +# - Use ChatSession: Tutorials/ChatSession.md +# - Understand LLamaContext: Tutorials/UnderstandLLamaContext.md +# - Get embeddings: Tutorials/GetEmbeddings.md +# - Quantize the model: Tutorials/Quantization.md +# +# - Advanced Tutorials: +# - Customize the native library loading: AdvancedTutorials/CustomizeNativeLibraryLoading.md +# +# - Integrations: +# - semantic-kernel integration: Integrations/semantic-kernel.md +# - kernel-memory integration: Integrations/kernel-memory.md +# - BotSharp integration: Integrations/BotSharp.md +# - Langchain integration: Integrations/Langchain.md +# +# - Examples: +# - Bacthed executor - multi-output to one input: Examples/BatchedExecutorFork.md +# - Batched executor - basic guidance: Examples/BatchedExecutorGuidance.md +# - Batched executor - rewinding to an earlier state: Examples/BatchedExecutorRewind.md + +theme: + name: material + static_templates: + - 404.html + language: 'en' + palette: + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: white + accent: red + toggle: + icon: material/weather-sunny + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: blue + accent: blue + toggle: + icon: material/weather-night + name: Switch to light mode + include_search_page: false + search_index_only: true + favicon: 'media/icon128.png' + icon: + logo: 'material/file-document' + features: + - content.action.edit + - navigation.instant + font: + text: 'Fira Sans' + code: 'Fira Mono' + +extra: + version: + provider: mike + +extra_css: + - 'css/extra.css?v=14' + +markdown_extensions: + - admonition + - def_list + - footnotes + - meta + - toc: + permalink: "" + slugify: !!python/name:pymdownx.slugs.uslugify + - pymdownx.arithmatex: + generic: true + - pymdownx.caret + - pymdownx.critic + - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:pymdownx.emoji.to_svg + - pymdownx.highlight: + linenums: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink + - pymdownx.mark + - pymdownx.snippets: + check_paths: true + - pymdownx.progressbar + - pymdownx.smartsymbols + - pymdownx.superfences: + custom_fences: + - name: math + class: arithmatex + format: !!python/name:pymdownx.arithmatex.fence_mathjax_format + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + - pymdownx.tabbed: + alternate_style: true \ No newline at end of file diff --git a/src/helpers/GenerateDocs/GenerateDocs.csproj b/src/helpers/GenerateDocs/GenerateDocs.csproj new file mode 100644 index 0000000000..f67f521030 --- /dev/null +++ b/src/helpers/GenerateDocs/GenerateDocs.csproj @@ -0,0 +1,9 @@ + + + + Exe + net8.0 + enable + + + diff --git a/src/helpers/GenerateDocs/Program.cs b/src/helpers/GenerateDocs/Program.cs new file mode 100644 index 0000000000..b78f5f77d4 --- /dev/null +++ b/src/helpers/GenerateDocs/Program.cs @@ -0,0 +1,37 @@ +var solutionDirectory = args.ElementAtOrDefault(0) ?? Path.GetFullPath(Path.Combine(Directory.GetCurrentDirectory(), "../../../../../..")); +var sampleDirectory = Path.Combine(solutionDirectory, "src", "tests", "OpenAI.IntegrationTests", "Examples"); +var mkDocsPath = Path.Combine(solutionDirectory, "mkdocs.yml"); + +var newDir = Path.Combine(solutionDirectory, "docs", "samples"); +Directory.CreateDirectory(newDir); + +File.Copy( + Path.Combine(solutionDirectory, "README.md"), + Path.Combine(solutionDirectory, "docs", "index.md")); + +Console.WriteLine($"Generating samples from {sampleDirectory}..."); +foreach (var path in Directory.EnumerateFiles(sampleDirectory, "*.cs", SearchOption.AllDirectories)) +{ + var code = await File.ReadAllTextAsync(path); + + var start = code.IndexOf("\n {", StringComparison.Ordinal); + var end = code.IndexOf("\n }", StringComparison.Ordinal); + code = code.Substring(start + 4, end - start + 4); + + var lines = code.Split('\n')[1..^2]; + code = string.Join('\n', lines.Select(x => x.Length > 8 ? x[8..] : string.Empty)); + + var newPath = Path.Combine(newDir, $"{Path.GetExtension(Path.GetFileNameWithoutExtension(path)).TrimStart('.')}.md"); + await File.WriteAllTextAsync(newPath, $@"```csharp +{code} +```"); +} + +var mkDocs = await File.ReadAllTextAsync(mkDocsPath); +var newMkDocs = mkDocs.Replace( + "# EXAMPLES #", + $"- Examples:{string.Concat(Directory.EnumerateFiles(Path.Combine(solutionDirectory, "docs", "samples"), "*.md") + .Select(x => $@" + - {Path.GetFileNameWithoutExtension(x)}: samples/{Path.GetFileNameWithoutExtension(x)}.md"))}"); +await File.WriteAllTextAsync(mkDocsPath, newMkDocs); +