Skip to content
Closed

Docs #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 23 additions & 1 deletion .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -40,4 +40,26 @@ jobs:

- name: push packages
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
run: dotnet nuget push **/*.nupkg -s https://f.feedz.io/davidfowl/featherhttp/nuget/index.json -ss https://f.feedz.io/davidfowl/featherhttp/symbols --skip-duplicate
run: dotnet nuget push **/*.nupkg -s https://f.feedz.io/davidfowl/featherhttp/nuget/index.json -ss https://f.feedz.io/davidfowl/featherhttp/symbols --skip-duplicate

generate-docs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
with:
persist-credentials: false
- name: generate gh-pages
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
run: |
cd ./docs
npm install
npm run generate:gh-pages
- name: deploy
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
uses: JamesIves/github-pages-deploy-action@releases/v3
Comment thread
RobotOptimist marked this conversation as resolved.
Resolved
with:
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
BRANCH: gh-pages
FOLDER: docs/dist
CLEAN: true
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ BenchmarkDotNet.Artifacts/
.gradle/
src/SignalR/clients/**/dist/
modules/
.nuxt/
dist/

# File extensions
*.aps
Expand Down
13 changes: 13 additions & 0 deletions docs/.editorconfig
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# editorconfig.org
root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false
4 changes: 4 additions & 0 deletions docs/.prettierrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"semi": false,
"singleQuote": true
}
115 changes: 115 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# Docs contribution guide

## How to Contribute

This project uses [Nuxt](https://nuxtjs.org/) which is a static site generator.

You will need to install [nodejs](https://nodejs.org/).
You can get the project running these commands from the `\docs` directory.

``` bash
#install the projects from npm
npm install

#serve the project with hot reload from localhost:3000
npm run dev

#if you want to see what files will be output for the static site then
npm run generate

#if, from your fork, you'd like to generate the docs site so you can see how it will look on github pages then you can run these commands:
npm run generate:gh-pages
npm run deploy
```

There are several ways you may want to contribute to the docs.

1. Add to the existing docs.
2. Create a brand new doc

### Add to the existing docs

Adding to the existing docs is easy.
First, in pages/examples find the .vue file that contains the documentation you seek to modify.
Then within the template tags you can make your modifications.

``` html
<template lang="md">
# Your contributions in markdown
...
</template>
```

You can optionally make contributions in regular html by removing `lang="md"` from the `<template>` tag.
And you also have all of the power of the [Vue](https://vuejs.org) instance that you can use from a script tag, below the `<template>` tag like so:

``` html
<template>
<p>Your Content</p>
</template>

<script>
export default {
//Vue stuff goes here
}
</script>
```

### Create a brand new doc

You can create a brand new doc by adding a new entry to `docs/store/topics.js`

``` JavaScript
/* In the state function there is an array of objects named list.
These entries determine the nav and buttons on the home page of docs.
They are displayed in the nav in order, with an appropriate category.
You can add your new entry to this list */
export const state = () => ({
list: [
{
title: 'Hello World',
category: 'Examples',
description: 'Shows how to create a minimal .NET Core server using Feather HTTP'
},
//...
{
title: 'SignalR',
category: 'Application Framework',
description: 'How to set up SignalR'
}
]
})

//Your new entry in the list would have this structure:
{
title: 'Your New Title'
category: 'The Category'
description: 'A small description of your new doc'
}

```
Adding this to the `docs/store/topics.js` will set up the routing and add appropriate buttons, but you still haven't created the doc.

Next you'll create a new file in `docs/pages/examples`. It will be a `.vue` file. Afterwards the explanation for modifying a doc applies.

Example
``` bash
cd docs/pages/examples
code my-new-docs.vue
#this will open the vue file in vscode for immediate editing. It won't appear in the directory until you save it though
```

Once the file is created you can set it up with a template tag. You don't have to create a script tag unless you need it.

``` html
<template>
</template>
```

If you want to write your doc in markdown you can add `lang="md"` to the template

``` html
<template lang="md">
```

And that's pretty much all there is to it! Thank you very much for contributing!
7 changes: 7 additions & 0 deletions docs/assets/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# ASSETS

**This directory is not required, you can delete it if you don't want to use it.**

This directory contains your un-compiled assets such as LESS, SASS, or JavaScript.

More information about the usage of this directory in [the documentation](https://nuxtjs.org/guide/assets#webpacked).
3 changes: 3 additions & 0 deletions docs/assets/css/tailwind.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';
7 changes: 7 additions & 0 deletions docs/components/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# COMPONENTS

**This directory is not required, you can delete it if you don't want to use it.**

The components directory contains your Vue.js Components.

_Nuxt.js doesn't supercharge these components._
26 changes: 26 additions & 0 deletions docs/components/card.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<template>
<div class="m-6 ml-0 lg:ml-6 lg:mb-0 lg:mr-0 p-10 pl-5 pr-5 shadow-md bg-green-200 rounded-lg">
<h2 class="text-2xl font-semibold rounded-lg text-blue-900">
{{title}}
</h2>
<p class="mt-2 pl-0">{{description}}</p>
<div class="mt-8 flex justify-end">
<nuxt-link class="underline p-3 pr-5 pl-5 bg-green-800 text-white font-bold rounded-lg" :to="`examples/${title.split(' ').join('-').toLowerCase()}`">Go to Tutorial</nuxt-link>
</div>
</div>
</template>

<script>
export default {
props: {
title: {
default: 'Default Title',
type: String
},
description: {
default: 'Default Description',
type: String
}
}
}
</script>
39 changes: 39 additions & 0 deletions docs/components/siteNav.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<template>
<nav>
<div class="flex flex-row justify-between w-full">
<div class="flex flex-col">
<nuxt-link class="text-green-800 text-xs font-bold underline" to="/">Home</nuxt-link>
<a class="text-green-800 text-xs font-bold underline" href="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/davidfowl/FeatherHttp">.NET Feather HTTP GitHub</a>
</div>
<button class="lg:hidden flex items-center" @click="toggleMenu">
<svg class="mr-1" height="32px" id="Layer_1" style="enable-background:new 0 0 32 32; color: white;" version="1.1" viewBox="0 0 32 32" width="32px" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<path fill="#38a169" d="m4,8.491662l24,0c1.104,0 2,-1.121245 2,-2.502779s-0.896,-2.502779 -2,-2.502779l-24,0c-1.104,0 -2,1.121245 -2,2.502779s0.896,2.502779 2,2.502779zm24,5.005559l-24,0c-1.104,0 -2,1.121245 -2,2.502779s0.896,2.502779 2,2.502779l24,0c1.104,0 2,-1.121245 2,-2.502779s-0.896,-2.502779 -2,-2.502779zm0,10.011118l-24,0c-1.104,0 -2,1.121245 -2,2.502779s0.896,2.502779 2,2.502779l24,0c1.104,0 2,-1.121245 2,-2.502779s-0.896,-2.502779 -2,-2.502779z"></path>
</svg>
<span class="ml-1 uppercase">Menu</span>
</button>
</div>
<topics-list class="lg:hidden" :isHidden="isHidden"></topics-list>
<div class="lg:max-w-md lg:w-1/5 hidden lg:block absolute mt-12">
<topics-list></topics-list>
</div>
</nav>
</template>

<script>
import topicsList from './topicsList';
export default {
data() {
return {
isHidden: true
}
},
methods: {
toggleMenu() {
this.isHidden = !this.isHidden;
}
},
components: {
topicsList
}
}
</script>
22 changes: 22 additions & 0 deletions docs/components/topicsList.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
<template>
<ul :class="{ 'max-h-none': isHidden, 'p-2 max-h-full transition-max-height': !isHidden }"
class="absolute leading-loose mt-1 rounded-lg font-bold bg-green-800 text-white w-4/5 transition-250 overflow-y-hidden lg:static lg:max-w-sm lg:w-full lg:mt-6">
<li v-for="topic in topics" :key="topic.title"><nuxt-link exact :to="`/examples/${topic.title.split(' ').join('-').toLowerCase()}`">{{topic.title}}</nuxt-link></li>
</ul>
</template>

<script>
export default {
props: {
isHidden: {
default: false,
type: Boolean
}
},
computed: {
topics() {
return this.$store.getters['topics/list'];
}
}
}
</script>
12 changes: 12 additions & 0 deletions docs/jsconfig.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"~/*": ["./*"],
"@/*": ["./*"],
"~~/*": ["./*"],
"@@/*": ["./*"]
}
},
"exclude": ["node_modules", ".nuxt", "dist"]
}
7 changes: 7 additions & 0 deletions docs/layouts/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# LAYOUTS

**This directory is not required, you can delete it if you don't want to use it.**

This directory contains your Application Layouts.

More information about the usage of this directory in [the documentation](https://nuxtjs.org/guide/views#layouts).
45 changes: 45 additions & 0 deletions docs/layouts/default.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<template>
<div class="bg-grey-100">
<site-nav class="p-10 pb-0"></site-nav>
<nuxt />
</div>
</template>

<script>
import siteNav from '../components/siteNav';
export default {
components: {
siteNav
}
}
</script>

<style lang="postcss">
.h1 {
@apply text-5xl text-green-800 font-semibold;
}
.h2 {
@apply text-4xl text-green-800
}
.h3 {
@apply text-3xl text-green-800
}
.code {
@apply bg-gray-400 p-1 font-mono
}
ol {
@apply list-decimal list-inside
}
section pre.language-csharp {
@apply bg-black pl-40
}
a {
@apply underline
}
p, ol {
@apply text-xl p-4;
@screen lg {
@apply text-base p-8;
}
}
</style>
8 changes: 8 additions & 0 deletions docs/middleware/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# MIDDLEWARE

**This directory is not required, you can delete it if you don't want to use it.**

This directory contains your application middleware.
Middleware let you define custom functions that can be run before rendering either a page or a group of pages.

More information about the usage of this directory in [the documentation](https://nuxtjs.org/guide/routing#middleware).
Loading