Skip to content
Snippets Groups Projects
Unverified Commit f2fbf2f1 authored by JohannesGarm's avatar JohannesGarm Committed by GitHub
Browse files

Merge pull request #37 from NORDUnet/feature/docs

[TechDebt] Adding a more structured prettier documentation layout.
parents a3686a80 25add7b4
Branches
Tags
No related merge requests found
Showing
with 562 additions and 32 deletions
......@@ -15,20 +15,20 @@ steps:
- PYTHONPATH=. trial test
services:
- name: database
image: postgres:12-alpine
environment:
POSTGRES_USER: opennsa
POSTGRES_PASSWORD: w1gWIn7NDGXjXMguiI2Qe05X
POSTGRES_DB: opennsatest
- name: database
image: postgres:12-alpine
environment:
POSTGRES_USER: opennsa
POSTGRES_PASSWORD: w1gWIn7NDGXjXMguiI2Qe05X
POSTGRES_DB: opennsatest
trigger:
event:
- push
- pull_request
---
kind: pipeline
---
kind: pipeline
name: docker
steps:
......@@ -51,3 +51,50 @@ trigger:
event:
- tag
- push
---
kind: pipeline
name: documentation
steps:
- name: Submodule sync
image: alpine/git
commands:
- "git submodule update --init --recursive"
- name: build
image: plugins/hugo:latest
settings:
extended: true
commands:
- cd website
- "apk add --update nghttp2-dev nodejs nodejs-npm npm wget"
- npm install -D --save autoprefixer postcss-cli postcss
- wget "https://github.com/gohugoio/hugo/releases/download/v0.91.0/hugo_extended_0.91.0_Linux-64bit.tar.gz"
- tar xvfz hugo_extended_0.91.0_Linux-64bit.tar.gz
- npm install
- "./hugo version"
- "./hugo --destination public --baseURL https://NORDUnet.github.io/opennsa/"
- name: publish
image: plugins/gh-pages
settings:
pages_directory: website/public
upstream_name: origin
remote_url: https://github.com/NORDUnet/opennsa.git
target_branch: gh-pages
force_push: true
delete: true
username:
from_secret: gh_username
password:
from_secret: gh_password
when:
branch:
- master
event: push
trigger:
branch:
- master
event:
- tag
- push
......@@ -13,3 +13,6 @@ docker-compose.override.yml
twistd.pid
.env
.DS_Store
node_modules
public
resources
[submodule "website/themes/docsy"]
path = website/themes/docsy
url = https://github.com/google/docsy.git
......@@ -26,6 +26,10 @@ only partially implemented.
* PostgreSQL for database
* Includes command line tool for basic operations
#### Documentation
Full and detailed documentation available [here](https://NORDUnet.github.io/opennsa/)
#### License
......
backport-ipaddress==0.1
cffi==1.1.2
characteristic==14.3.0
cryptography==0.9.3
enum34==1.0.4
idna==2.0
ipaddress==1.0.14
psycopg2==2.6.1
pyasn==1.5.0b6
pyasn1==0.1.8
pyasn1-modules==0.0.7
pycparser==2.14
pycrypto==2.6.1
pyOpenSSL>=17.5.0
python-dateutil==1.5
service-identity==14.0.0
six==1.9.0
twistar=>2.0
Twisted=>19.7.0
wheel==0.24.0
zope.interface==4.1.2
lts/*
# How to Contribute
We'd love to accept your patches and contributions to this project. There are
just a few small guidelines you need to follow.
## Contributor License Agreement
Contributions to this project must be accompanied by a Contributor License
Agreement. You (or your employer) retain the copyright to your contribution;
this simply gives us permission to use and redistribute your contributions as
part of the project. Head over to <https://cla.developers.google.com/> to see
your current agreements on file or to sign a new one.
You generally only need to submit a CLA once, so if you've already submitted one
(even if it was for a different project), you probably don't need to do it
again.
## Code reviews
All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
information on using pull requests.
## Community Guidelines
This project follows
[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
FROM klakegg/hugo:ext-alpine
RUN apk add git
# Docsy Example
[Docsy][] is a [Hugo theme][] for technical documentation sites, providing easy
site navigation, structure, and more. This **Docsy Example Project** uses the
Docsy theme and provides a skeleton documentation structure for you to use. You
can clone/copy this project and edit it with your own content, or use it as an
example.
In this project, the Docsy theme is included as a Git submodule:
```bash
$ git submodule
...<hash>... themes/docsy (remotes/origin/HEAD)
```
You can find detailed theme instructions in the [Docsy user guide][].
This Docsy Example Project is hosted on [Netlify][] at [example.docsy.dev][].
You can view deploy logs from the [deploy section of the project's Netlify
dashboard][deploys], or this [alternate dashboard][].
This is not an officially supported Google product. This project is currently maintained.
## Using the Docsy Example Project as a template
A simple way to get started is to use this project as a template, which gives you a site project that is set up and ready to use. To do this:
1. Click **Use this template**.
2. Select a name for your new project and click **Create repository from template**.
3. Make your own local working copy of your new repo using git clone, replacing https://github.com/my/example.git with your repo’s web URL:
```bash
git clone --recurse-submodules --depth 1 https://github.com/my/example.git
```
You can now edit your own versions of the site’s source files.
If you want to do SCSS edits and want to publish these, you need to install `PostCSS`
```bash
npm install
```
## Running the website locally
Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io).
You can find out more about how to install Hugo for your environment in our
[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide.
Once you've made your working copy of the site repo, from the repo root folder, run:
```
hugo server
```
## Running a container locally
You can run docsy-example inside a [Docker](https://docs.docker.com/)
container, the container runs with a volume bound to the `docsy-example`
folder. This approach doesn't require you to install any dependencies other
than [Docker Desktop](https://www.docker.com/products/docker-desktop) on
Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/)
on Linux.
1. Build the docker image
```bash
docker-compose build
```
1. Run the built image
```bash
docker-compose up
```
> NOTE: You can run both commands at once with `docker-compose up --build`.
1. Verify that the service is working.
Open your web browser and type `http://localhost:1313` in your navigation bar,
This opens a local instance of the docsy-example homepage. You can now make
changes to the docsy example and those changes will immediately show up in your
browser after you save.
### Cleanup
To stop Docker Compose, on your terminal window, press **Ctrl + C**.
To remove the produced images run:
```console
docker-compose rm
```
For more information see the [Docker Compose
documentation](https://docs.docker.com/compose/gettingstarted/).
## Troubleshooting
As you run the website locally, you may run into the following error:
```
➜ hugo server
INFO 2021/01/21 21:07:55 Using config file:
Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
Built in 288 ms
Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache
```
This error occurs if you have not installed the extended version of Hugo.
See our [user guide](https://www.docsy.dev/docs/getting-started/) for instructions on how to install Hugo.
[alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys
[deploys]: https://app.netlify.com/sites/docsy-example/deploys
[Docsy user guide]: https://docsy.dev/docs
[Docsy]: https://github.com/google/docsy
[example.docsy.dev]: https://example.docsy.dev
[Hugo theme]: https://gohugo.io/themes/installing-and-using-themes/
[Netlify]: https://netlify.com
/*
Add styles or override variables from the theme here.
*/
baseURL = "/"
title = "OpenNSA"
enableRobotsTXT = true
# Hugo allows theme composition (and inheritance). The precedence is from left to right.
theme = ["docsy"]
# Will give values to .Lastmod etc.
enableGitInfo = true
# Language settings
contentDir = "content"
defaultContentLanguage = "en"
defaultContentLanguageInSubdir = false
# Useful when translating.
enableMissingTranslationPlaceholders = true
# Comment out to enable taxonomies in Docsy
# disableKinds = ["taxonomy", "taxonomyTerm"]
# You can add your own taxonomies
[taxonomies]
tag = "tags"
category = "categories"
[params.taxonomy]
# set taxonomyCloud = [] to hide taxonomy clouds
taxonomyCloud = ["tags", "categories"]
# If used, must have same lang as taxonomyCloud
taxonomyCloudTitle = ["Tag Cloud", "Categories"]
# set taxonomyPageHeader = [] to hide taxonomies on the page headers
taxonomyPageHeader = ["tags", "categories"]
# Highlighting config
pygmentsCodeFences = true
pygmentsUseClasses = false
# Use the new Chroma Go highlighter in Hugo.
pygmentsUseClassic = false
#pygmentsOptions = "linenos=table"
# See https://help.farbox.com/pygments.html
pygmentsStyle = "tango"
## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday
[blackfriday]
plainIDAnchors = true
hrefTargetBlank = true
angledQuotes = false
latexDashes = true
# Image processing configuration.
[imaging]
resampleFilter = "CatmullRom"
quality = 75
anchor = "smart"
[services]
[services.googleAnalytics]
# Comment out the next line to disable GA tracking. Also disables the feature described in [params.ui.feedback].
id = "UA-00000000-0"
# Language configuration
[languages]
[languages.en]
title = "OpenNSA"
description = "A Docsy example site"
languageName ="English"
# Weight used for sorting.
weight = 1
[markup]
[markup.goldmark]
[markup.goldmark.renderer]
unsafe = true
[markup.highlight]
# See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
style = "tango"
# Uncomment if you want your chosen highlight style used for code blocks without a specified language
# guessSyntax = "true"
# Everything below this are Site Params
# Comment out if you don't want the "print entire section" link enabled.
[outputs]
section = ["HTML", "print", "RSS"]
[params]
copyright = "The Docsy Authors"
privacy_policy = "https://policies.google.com/privacy"
# First one is picked as the Twitter card image if not set on page.
# images = ["images/project-illustration.png"]
# Menu title if your navbar has a versions selector to access old versions of your site.
# This menu appears only if you have at least one [params.versions] set.
version_menu = "Releases"
# Flag used in the "version-banner" partial to decide whether to display a
# banner on every page indicating that this is an archived version of the docs.
# Set this flag to "true" if you want to display the banner.
archived_version = false
# The version number for the version of the docs represented in this doc set.
# Used in the "version-banner" partial to display a version number for the
# current doc set.
version = "0.0"
# A link to latest version of the docs. Used in the "version-banner" partial to
# point people to the main doc site.
url_latest_version = "https://example.com"
# Repository configuration (URLs for in-page links to opening issues and suggesting changes)
github_repo = "https://github.com/google/docsy-example"
# An optional link to a related project repo. For example, the sibling repository where your product code lives.
github_project_repo = "https://github.com/google/docsy"
# Specify a value here if your content directory is not in your repo's root directory
# github_subdir = ""
# Uncomment this if you have a newer GitHub repo with "main" as the default branch,
# or specify a new value if you want to reference another branch in your GitHub links
github_branch= "main"
# Google Custom Search Engine ID. Remove or comment out to disable search.
#gcs_engine_id = "d72aa9b2712488cc3"
# Enable Algolia DocSearch
algolia_docsearch = false
# Enable Lunr.js offline search
offlineSearch = true
offlineSearchSummaryLength = 1000
offlineSearchMaxResults = 25
# Enable syntax highlighting and copy buttons on code blocks with Prism
prism_syntax_highlighting = false
# User interface configuration
[params.ui]
# Set to true to disable breadcrumb navigation.
breadcrumb_disable = false
# Set to true to disable the About link in the site footer
footer_about_disable = false
# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top navbar
navbar_logo = true
# Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage.
navbar_translucent_over_cover_disable = false
# Enable to show the side bar menu in its compact state.
sidebar_menu_compact = false
# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
sidebar_search_disable = false
# Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events.
# This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set.
# If you want this feature, but occasionally need to remove the "Feedback" section from a single page,
# add "hide_feedback: true" to the page's front matter.
[params.ui.feedback]
enable = true
# The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
yes = 'Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
no = 'Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
# Adds a reading time to the top of each doc.
# If you want this feature, but occasionally need to remove the Reading time from a single page,
# add "hide_readingtime: true" to the page's front matter
[params.ui.readingtime]
enable = false
[params.links]
# End user relevant links. These will show up on left side of footer and in the community page if you have one.
[[params.links.user]]
name = "User mailing list"
url = "https://example.org/mail"
icon = "fa fa-envelope"
desc = "Discussion and help from your fellow users"
[[params.links.user]]
name ="Twitter"
url = "https://example.org/twitter"
icon = "fab fa-twitter"
desc = "Follow us on Twitter to get the latest news!"
[[params.links.user]]
name = "Stack Overflow"
url = "https://example.org/stack"
icon = "fab fa-stack-overflow"
desc = "Practical questions and curated answers"
# Developer relevant links. These will show up on right side of footer and in the community page if you have one.
[[params.links.developer]]
name = "GitHub"
url = "https://github.com/google/docsy"
icon = "fab fa-github"
desc = "Development takes place here!"
[[params.links.developer]]
name = "Slack"
url = "https://example.org/slack"
icon = "fab fa-slack"
desc = "Chat with other project developers"
[[params.links.developer]]
name = "Developer mailing list"
url = "https://example.org/mail"
icon = "fa fa-envelope"
desc = "Discuss development issues around the project"
+++
title = "OpenNSA"
linkTitle = "OpenNSA"
+++
{{< blocks/cover title="Welcome to OpenNSA: an implementation of the Network Service Interface (NSI)." image_anchor="top" height="full" color="orange" >}}
<div class="mx-auto">
<a class="btn btn-lg btn-primary mr-3 mb-4" href="{{< relref "/docs" >}}">
Documentation <i class="fas fa-arrow-alt-circle-right ml-2"></i>
</a>
<a class="btn btn-lg btn-secondary mr-3 mb-4" href="https://github.com/NORDUnet/opennsa">
Download <i class="fab fa-github ml-2 "></i>
</a>
<a class="btn btn-lg btn-primary mr-3 mb-4" href="https://github.com/NORDUnet/opennsa/blob/master/docs/GFD.237.pdf">
Spec <i class="fab fa-github ml-2 "></i>
</a>
{{< blocks/link-down color="info" >}}
</div>
{{< /blocks/cover >}}
{{% blocks/lead color="primary" %}}
OpenNSA is currently in a state of heavy development, and many features are only partially implemented.
OpenNSA features: Plugable backends,DUD backend for easy testing, Easy creation of NML topology, command line tool for basic operations, path finding to do multi-domain circuit creation
{{% /blocks/lead %}}
---
title: About Goldydocs
linkTitle: About
menu:
main:
weight: 10
---
{{< blocks/cover title="About Goldydocs" image_anchor="bottom" height="min" >}}
<p class="lead mt-5">A sample site using the Docsy Hugo theme.
</p>
{{< /blocks/cover >}}
{{% blocks/lead %}}
Goldydocs is a sample site using the <a href="https://github.com/google/docsy">Docsy</a> Hugo theme that shows what it can do and provides you with a template site structure. It’s designed for you to clone and edit as much as you like. See the different sections of the documentation and site for more ideas.
{{% /blocks/lead %}}
{{< blocks/section >}}
<div class="col-12">
<h1 class="text-center">This is another section</h1>
</div>
{{< /blocks/section >}}
{{< blocks/section >}}
<div class="col-12">
<h1 class="text-center">This is another section</h1>
</div>
{{< /blocks/section >}}
website/content/about/featured-background.jpg

791 KiB

---
categories: ["Developer"]
tags: ["developer","docs", "guide", "backends"]
title: "Backends"
linkTitle: "Backends"
weight: 88
description: >
Backends Documentation
---
Further document the various backends available.
Brocade
--------
---
categories: ["Developer"]
tags: ["developer","docs", "guide", "backends"]
title: "Brocade"
linkTitle: "Brocade"
weight: 2
description: >
Backends Documentation
---
# Brocade
**Config snippet:**
......
---
categories: ["Developer"]
tags: ["developer","docs", "guide"]
title: "Developer"
linkTitle: "Developer"
weight: 2
description: >
Developer Documentation
---
This is a collection of developer guides and instruction that are tailored to the developer experience though might be helpful to the casual user.
---
categories: ["Developer"]
tags: ["install", "developer"]
title: "Quick Developer Guide"
linkTitle: "Quick Developer Guide"
date: 2021-12-16
description: >
Quick Developer Guide
---
# Quick Developer Guide
......
---
categories: ["Developer"]
tags: ["install", "developer"]
title: "Testing"
linkTitle: "Testing"
date: 2021-12-16
description: >
Quick Developer Guide
---
How to run the the unit/integration tests for OpenNSA
Make sure all the requirements are installed. Then:
......
---
categories: ["Legacy", "Placeholders"]
tags: ["legacy","docs"]
title: "Legacy Documentation"
linkTitle: "Legacy"
weight: 99
description: >
Legacy Documentation
---
This is a collection of legacy documents that are likely no longer needed but kept for posterity's sake.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment