Skip to content

Commit 8144367

Browse files
GelberMSkylineGelberMSkyline
authored
Initial commit
0 parents  commit 8144367

22 files changed

+1114
-0
lines changed

‎.github/dependabot.yml

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Set update schedule for GitHub Actions
2+
3+
version: 2
4+
updates:
5+
6+
- package-ecosystem: "github-actions"
7+
directory: "/"
8+
schedule:
9+
# Check for updates to GitHub Actions every week
10+
interval: "weekly"

‎.github/workflows/github-actions-workflow.yml

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Azure Static Web Apps CI/CD
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
# pull_request:
8+
# types: [opened, synchronize, reopened, closed]
9+
# branches:
10+
# - main
11+
12+
jobs:
13+
build_job:
14+
runs-on: windows-latest
15+
name: Build Job
16+
steps:
17+
- uses: actions/checkout@v4
18+
with:
19+
submodules: true
20+
- name: install DocFX
21+
run: dotnet tool update -g docfx
22+
env:
23+
CI: true
24+
- name: build documentation
25+
run: |
26+
docfx build --warningsAsErrors
27+
- name: publish results
28+
uses: actions/upload-artifact@v4
29+
with:
30+
name: Documentation
31+
path: _site/

‎.gitignore

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
###############
2+
# folder #
3+
###############
4+
/**/DROP/
5+
/**/TEMP/
6+
/**/packages/
7+
/**/bin/
8+
/**/obj/
9+
_site

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Skyline Communications
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Documentation Repository
2+
3+
Welcome to our Documentation Repository! 🚀
4+
5+
## Overview
6+
7+
This repository serves as the central hub when we want to work together with our DevOps Professionals on Project Documentation. Clear and comprehensive documentation is crucial for understanding our deliverables, projects, and complex environments. It not only benefits us internally but also plays a vital role in ensuring our customers have a seamless experience and clear understanding of the environment.
8+
9+
Navigate to our documentation: [Home Page](index.md)
10+
11+
> [!IMPORTANT]
12+
> Please read carefully the guidelines outlined in the [Getting Started](xref:gettingStarted)
13+
14+
## Why Documentation Matters
15+
16+
Documentation provides a shared understanding and knowledge base for our team and our customers. It serves as a reference point, enabling us to:
17+
18+
- **Improve Collaboration:** Working together with customers on documentation ensures we capture their unique perspectives and requirements, leading to better solutions.
19+
- **Ensure Clarity:** Having a clear overview from the beginning helps us build a strong foundation, reducing confusion and misunderstandings.
20+
- **Enhance Customer Experience:** Well-documented processes and products empower our customers, enabling them to use our solutions effectively.
21+
22+
## How to Contribute
23+
24+
We encourage all team members to actively contribute to our documentation efforts.
25+
26+
> [!NOTE]
27+
> Of course, it should be clear that we are doing this effort as part of our deliverables, and hence it should be clear this is categorized as **engineering work (billable)**.
28+
29+
Want to contribute? Check out [Contributing to the project documentation](xref:contributing)
30+
31+
Here's how you can get involved:
32+
33+
1. **Collaborate with Customers:** Engage with our users to gather insights and feedback. Their input is invaluable in creating user-friendly documentation.
34+
35+
2. **Add and Update Content:** Contribute by adding new documentation or updating existing content. Whether it's a guide, tutorial, or FAQ, your contributions make a difference.
36+
37+
3. **Review and Improve:** Review existing documentation to identify areas of improvement. Even small edits can enhance clarity and usability.
38+
39+
## How to get started
40+
41+
> [!IMPORTANT]
42+
> For Skyline employees: Please include a link from [InternalDocs - ProjectDocs](https://internaldocs.skyline.be/Projects/Projects.html) to this repository
43+
44+
1. Follow the steps described at [Creating a repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template)
45+
1. While creating the new repository, take into account the [GitHub Repository Guidelines](https://docs.dataminer.services/develop/CICD/Skyline%20Communications/Github/Use_Github_Guidelines.html) described in the DataMiner Docs.
46+
1. Suggested Naming Convention: {customerAcronym}-DOC-NameOfProject
47+
2. Add/Change the license according to what is agreed with the customer
48+
3. Add GitHub repository topics: dataminer-doc
49+
1. Once the repository is cloned, add your custom documentation available in the 'articles' folder. Suggest structure:
50+
1. overview.md: the purpose of the environment is documented with a high-level overview of the most important components
51+
2. features.md: key components of the environment, typically with subfolders
52+
3. infrastructure.md: user-oriented POV explanation of how the environment is built (architecture, database types, failover, etc.)
53+
1. You can build a test build by following [Contributing to the project documentation](xref:contributing).
54+
1. When you are happy with your changes, push them to the GitHub repository.
55+
1. GitHub actions will make an artifact available that you put on your DataMiner which will host this as a static website. If you are interested, follow the steps in the section below.
56+
57+
### Tips
58+
59+
1. Change this README, and add a link to your front page so it is easily accessible through GitHub as well.
60+
1. Add image files to the *images* folder if the file is referencing an image.
61+
1. Consider using Mermaid for creating diagrams, etc. When creating images using Mermaid, take into account the dark and light themes. Make sure the images are readable in both themes.
62+
1. Do not create lengthy pages. It is preferred to create smaller pages as the search is performed on page level.
63+
64+
## GitHub Actions and Hosting
65+
66+
We have set up GitHub Actions to automate the building process of our documentation artifacts. Through this automation, we can host a static website (e.g. on IIS) with the content of this repository. This ensures that our documentation is always up-to-date and easily accessible to both our team and users.
67+
68+
Our documentation artifacts are generated automatically through GitHub Actions. When making changes, simply commit your updates to the repository. GitHub Actions will take care of the rest, ensuring our static website is continuously updated. For now, there's no automatic deployment available, so we still need to manually copy the artifacts to a folder under IIS.
69+
70+
1. On your GitHub repository, go to the tab 'Actions'
71+
1. Download the 'Documentation.zip'
72+
1. Extract the archive in your DataMiner in the location 'C:\Skyline DataMiner\Webpages\Documentation'. Note the 'Documentation' folder is not available by default and can be created.
73+
1. Configure the default file in ISS
74+
1. Go to Internet Information Services (IIS) Manager
75+
1. Find the 'Documentation' folder you have added
76+
1. In the 'IIS' section, double click on 'Default Document'
77+
1. Include the index.html on the list.
78+
1. Navigate to 'https://`hostname`/Documentation' to view the website
79+
80+
## Let's Build Something Great Together!
81+
82+
Thank you for contributing to our documentation efforts. By collaborating, adding new content, and maintaining the existing resources, we can create a knowledge base that benefits everyone. Together, let's build exceptional products, provide outstanding support, and deliver an exceptional experience to our customers.
83+
84+
Happy documenting! 📚✨

‎articles/Features/feature_1.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
uid: feature1
3+
---
4+
5+
# Feature 1
6+
7+
My first feature.

‎articles/Features/feature_2.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
uid: feature2
3+
---
4+
5+
# Feature 2
6+
7+
My second feature.

‎articles/GettingStarted/contributing.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
uid: contributing
3+
---
4+
5+
# Contributing to the project documentation
6+
7+
You can contribute to this documentation in the same way as you contribute to docs.dataminer.services. See [Contributing to the DataMiner docs](https://docs.dataminer.services/CONTRIBUTING.html).
8+
9+
> [!NOTE]
10+
> Since the switch to DocFX 2.60 and higher, creating a test build is different for docs and for internaldocs. See [Creating a test build](#creating-a-test-build).
11+
12+
## Creating a test build
13+
14+
1. Make sure [DocFX is correctly installed](https://docs.dataminer.services/CONTRIBUTING.html#installing-and-configuring-docfx).
15+
16+
> [!NOTE]
17+
> Use the information on the referenced page only to install DocFX. For the test build, continue with the steps below.
18+
19+
1. If no Terminal pane is open in Visual Studio Code, go to *Terminal > New Terminal*.
20+
21+
1. In the Terminal pane, do the following:
22+
23+
1. Enter `clear` to clear the terminal.
24+
25+
1. Enter `docfx build` to make a test build.
26+
27+
1. Enter `docfx serve _site` to make this test build available through a local webserver.
28+
29+
1. In a browser, go to <http://localhost:8080/> to preview the website.
30+
31+
> [!TIP]
32+
> If you are not able to access localhost:8080, you can specify a different port by entering e.g. `docfx serve _site -p 8090`.
33+
34+
When you have finished previewing the website, in the Terminal pane, press ENTER to exit the preview mode.

‎articles/GettingStarted/gettingStarted.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
uid: gettingStarted
3+
---
4+
5+
# Project documentation template
6+
7+
## Guidelines
8+
9+
> [!IMPORTANT]
10+
> Please include a link from [InternalDocs - ProjectDocs](https://internaldocs.skyline.be/Projects/Projects.html) to this repository
11+
12+
1. Use the [GitHub Guidelines](https://docs.dataminer.services/develop/CICD/Skyline%20Communications/Github/Use_Github_Guidelines.html) by adhering the naming convention ({customerAcronym}-DOC-{itemName}) and GitHub topic (dataminer-doc)
13+
1. In the README, add a link to your front page so it is easily accessible through GitHub as well.
14+
1. Consider using Mermaid for creating diagrams, etc. When creating images using Mermaid, take into account the dark and light themes. Make sure the images are readable in both themes.
15+
1. Add image files to the *images* folder if the file is referencing an image.
16+
1. Do not create lengthy pages. It is preferred to create smaller pages as the search is performed on page level.
17+
1. It's recommended to not change the css for now, as soon a new version of DocFX will be applied.
18+
1. Refer to below sections for more information.

‎articles/GettingStarted/markdown.md

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
uid: markdown
3+
---
4+
5+
# Markdown
6+
7+
For more information regarding markdown, refer to [Markdown](http://daringfireball.net/projects/markdown/).
8+
Note that DocFx supports DocFx flavored markdown, allowing additional things such as creating diagrams (using Mermaid). For more information refer to [DocFx markdown](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet).
9+
10+
## Cross references
11+
12+
It is good practice to add a UID to every markdown file.
13+
14+
```markdown
15+
---
16+
uid: <myTopicUid>
17+
---
18+
```
19+
20+
In the toc.yml file you can then reference a page via this UID using `topicUid`.
21+
22+
```yml
23+
topicUid: markdown
24+
```
25+
26+
To reference another file in a markdown file, you can use xref.
27+
For example:
28+
29+
```markdown
30+
[Markdown page](xref:markdown)
31+
```
32+
33+
For more information refer to [Links and Cross References](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html).
34+
35+
## Examples DocFx flavored markdown
36+
37+
### Mermaid diagram
38+
39+
```mermaid
40+
flowchart LR
41+
42+
A[Hard] -->|Text| B(Round)
43+
B --> C{Decision}
44+
C -->|One| D[Result 1]
45+
C -->|Two| E[Result 2]
46+
```
47+
48+
### Math expressions
49+
50+
This sentence uses `$` delimiters to show math inline: $\sqrt{3x-1}+(1+x)^2$
51+
52+
**The Cauchy-Schwarz Inequality**
53+
54+
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

‎articles/features.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
uid: features
3+
---
4+
5+
# Features
6+
7+
The key components are explained in this section. First of all, we should start with the most important DataMiner Modules being used, behind the scenes but also from a user POV.
8+
Next to that, we can go deeper into the most important integrations and building blocks of the environment. Nothing prevents you from using subpages, but keep it digestible and to the point. If possible, some links are added to CI/CD artifacts or development repositories of these components.
9+
10+
Examples:
11+
12+
* This could be ticketing which goes from the alarm console (with hyperlinks) towards an Automation Scripts which will interact with an Element which is interacting with Jira.
13+
* This could be an SRM environment, where you mention how bookings are typically created (e.g. user-defined API, an element polling data, booking wizard, etc.) and potentially have subpages with the most important flavors or components within this solution.
14+
* This could be a key 'manager' element doing a lot of behind-the-scenes logic in the background.
15+
* This could be a low-code APP, quickly summarizing the most important pages & visuals. Also, the most important scripts being used for interaction or queries are quickly discussed.

‎articles/infrastructure.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
uid: infrastructure
3+
---
4+
5+
# Infrastructure
6+
7+
A user-oriented POV explanation of how the environment is built. First of all, it should be clear what the different stages are; i.e. do we have regression, staging, and/or pre-production DataMiner Agents, besides the production?
8+
9+
10+
Secondly, a high-overview explanation is done to understand:
11+
12+
* How many agents are in the cluster?
13+
* Where are they hosted (physical server, VMs on same/different server, SAN or SSD, etc.)
14+
* Do we have failover and if so how many agents?
15+
* What is the type of database in use?
16+
* External or local Cassandra
17+
* STaaS
18+
* Indexing engine (OpenSearch or ElasticSearch)
19+
* Where are backups typically stored (locally or network share)?

‎articles/overview.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
uid: overview
3+
---
4+
5+
# Overview
6+
7+
On this page, the purpose of the environment is documented with a high-level overview of the most important components (preferably in a clear visual (diagram)). Next to this, the importance of the cluster environment is indicated, compared to the other environments.
8+
9+
Adding to this, optionally you can also indicate the most important projects (with Collaboration links) in this environment. If you have multiple projects (e.g. extensions) you can summarize this in sub-levels.

‎articles/toc.yml

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
items:
2+
- name: Overview
3+
topicUid: overview
4+
- name: Features
5+
topicUid: features
6+
items:
7+
- name: Feature 1
8+
topicUid: feature1
9+
- name: Feature 2
10+
topicUid: feature2
11+
- name: Infrastructure
12+
topicUid: infrastructure
13+
- name: Getting started
14+
topicUid: gettingStarted
15+
items:
16+
- name: Markdown
17+
topicUid: markdown
18+
- name: Contributing
19+
topicUid: contributing

‎docfx.json

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"build": {
3+
"content": [
4+
{
5+
"files": [
6+
"articles/**.md",
7+
"articles/**/toc.yml",
8+
"toc.yml",
9+
"*.md"
10+
]
11+
}
12+
],
13+
"resource": [
14+
{
15+
"files": [
16+
"images/**"
17+
]
18+
}
19+
],
20+
"dest": "_site",
21+
"globalMetadata": {
22+
"_appTitle": "Project Documentation",
23+
"_appFooter": "© Skyline Communications 2024",
24+
"_enableSearch": true,
25+
"_enableNewTab": true
26+
},
27+
"globalMetadataFiles": [],
28+
"fileMetadataFiles": [],
29+
"template": [
30+
"default",
31+
"modern",
32+
"templates/skyline"
33+
],
34+
"postProcessors": [ "ExtractSearchIndex" ],
35+
"markdownEngineName": "markdig",
36+
"noLangKeyword": false,
37+
"keepFileLink": false,
38+
"cleanupCacheHistory": false,
39+
"disableGitFeatures": false
40+
}
41+
}

‎images/NonEmptyFolder.txt

Whitespace-only changes.

0 commit comments

Comments
 (0)