You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+24-53Lines changed: 24 additions & 53 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,15 +4,27 @@ Read more about the method at (https://www.apiopscycles.com/)
4
4
5
5
This repository contains the source for the APIOps Cycles method, including resources such as canvases. It can be used for multiple purposes, such as the method website (https://www.apiopscycles.com/), which is generated from these files, and the Canvas Creator tool that allows creating, importing and exporting the canvases, and provides a UI. (https://canvascreator.apiopscycles.com/).
6
6
7
-
## Requirements
7
+
## License
8
8
9
-
You can use the JSON files as is and download a .zip file or clone the repository. You can also install them using `npm install apiops-cycles-method-data`.
9
+
All content in this repository is provided under Apache 2 license for programmable use, the content and the design of the canvases is under the CC BY-SA 4.0 license unless noted otherwise.
10
+
APIOps and APIOps Cycles are trademarks owned by Osaango Oy (https://www.osaango.com). Permission is given to use them in connection with the method, for community purposes. Contact Osaango for partnerships, or sponsoring to support the method development. See method website for current partners (https://www.apiopscycles.com/)
10
11
11
-
This package can also be consumed directly from Git:
│ ├── assets/ # APIOps Cycles logos and other core assets which you might need in your tooling or product
18
+
│ ├── data/method/ # The Method JSON files (structure, relationship, and guideline content)
19
+
│ ├── data/method/canvas/ # The Canvases included in the method as JSON files (also used by tools like Canvas Creator)
20
+
│ ├── snippets/ # Raw markdown files used for long content for resource docs (only essential extensions for the json files)
21
+
├── scripts/ # Utility scripts
22
+
└── package.json
23
+
```
24
+
25
+
## Requirements
26
+
27
+
You can use the JSON files as is and download a .zip file or clone the repository. You can also install them using `npm install apiops-cycles-method-data`.
16
28
17
29
The module exposes top-level exports so you can import the data files directly, for example:
18
30
@@ -36,27 +48,6 @@ Install dependencies once with:
36
48
npm install
37
49
```
38
50
39
-
### Canvas editor
40
-
41
-
Interactive canvases on the site are powered by the [Canvas Creator](https://canvascreator.apiopscycles.com) tool. The component is installed from npm so make sure to run `npm install` before building or running the dev server.
42
-
43
-
## Local development
44
-
45
-
Run a local dev server:
46
-
47
-
```bash
48
-
npm run dev
49
-
```
50
-
51
-
This command copies the resource files to `public/` so that links to canvas JSON
52
-
files work during development.
53
-
54
-
Build the production site:
55
-
56
-
```bash
57
-
npm run build
58
-
```
59
-
60
51
## Contributing
61
52
62
53
### Reporting issues or requesting features
@@ -65,17 +56,13 @@ If you spot a problem in the documentation or have an idea for new content, plea
65
56
66
57
### Editing or adding content
67
58
68
-
Most pages are generated from the JSON files in `src/data/method/`. These base files (`lines.json`, `stations.json`, `resources.json`, `criteria.json` and `station-criteria.json`) are not localized and live at the root of the folder. Textual values in them reference label keys. English labels are in `src/data/method/en-US` and translations are provided in `labels.lines.json`, `labels.stations.json`, `labels.resources.json` and `labels.criteria.json` under each locale folder. Some longer or more complex resource pages like the API Audit Checklist also use markdown snippets `src/snippets/` linked to the `resources.json`. Do not use any frontmatter in the snippet files. Any supported markdown markup is ok. See references from [Starlight markdown reference](https://starlight.astro.build/guides/authoring-content/) and [Extended markdown reference](https://www.markdownguide.org/extended-syntax/).
69
-
70
-
Each station page lists the station's entry criteria followed by the next core station's criteria as exit criteria.
59
+
The main method files (instructions, guidelines, method structure) is located in the the JSON files at `src/data/method/`. These base files (`lines.json`, `stations.json`, `resources.json`, `criteria.json` and `station-criteria.json`) are not localized and live at the root of the folder. Textual values in them reference label keys. English labels are in `src/data/method/en-US` and translations are provided in `labels.lines.json`, `labels.stations.json`, `labels.resources.json` and `labels.criteria.json` under each locale folder. Some longer or more complex resource pages like the API Audit Checklist also use markdown snippets `src/snippets/` linked to the `resources.json`. Do not use any frontmatter in the snippet files. Any supported markdown markup is ok. See references from [Starlight markdown reference](https://starlight.astro.build/guides/authoring-content/) and [Extended markdown reference](https://www.markdownguide.org/extended-syntax/).
71
60
72
-
After editing these files, run `npm run generate:method` to update the Markdown files in `src/content/docs/`. Note that the generated markdown files are not inlcuded in version control to avoid confusion on where editing should happen.
73
-
74
-
For fixes in the Markdown files included in version control under `src/content/docs/`, edit them directly.
61
+
Each station links to specific entry criteria followed by the next core station's criteria as exit criteria.`criteria.json`, `station-criteria.json` and `labels.criteria.json`
75
62
76
63
#### Editing existing content of Method pages (metrolines, core- and substations, resources).
77
64
1. Go to `src/data/method/en` and edit the content in English (English is considered the master langauge, and for the translations to work for other languages, it must always be the first to be edited).
78
-
2. Validate that your changes work TODO
65
+
2. Validate that your changes work by running the schema validations (`npm test`)
79
66
3. Follow the translation guide if you are able to translate the content to other languages manually or automatically.
80
67
4. Commit your code and make a pull request.
81
68
5. If you were not able to create the translations of your changes to all languages, create an issue for in the repository for the translations.
@@ -90,6 +77,8 @@ Content under `src/snippets/` and `src/assets/resource/` can be localized by pla
90
77
91
78
Create/Edit the translaton files and put them in to the `src/data/method/` with correct language subfolder manually, or...
92
79
80
+
Install json-autotranslate with `npm install json-autotranslate`. It is not included as a dev-dependency at all, because most people would never need it and it's installing over 200+ dependencies.
81
+
93
82
1. Create a copy of the `src/data/method/` folder as `.json-autotranslate-cache` (in the root of the project). The cache is not under version control.
94
83
2. Create a new folder under the `src/data/locale` (this is a temporary folder, not versioned ) using the 2-letter ISO-code for the new language you are about to translate, e.g. `src/data/locale/fi` if creating translations for Finnish language.
95
84
3. Make sure the target language folder is *empty*, e.g. `src/data/locale/fi`. The folder really needs to be empty, even if there are already translations done for this language.
@@ -112,26 +101,8 @@ Create/Edit the translaton files and put them in to the `src/data/method/` with
112
101
9. If the translated files look ok, go to the translation cache folder `.json-autotranslate-cache` and look for the folder in the target language, i.e. `.json-autotranslate-cache/fi`.
113
102
- (Explanation: For some strange reason the plugin writes the contents in different (nested) format in the source folder (i.e. `locales`) than what it can actually read during the next translation round. The flat format it uses in the cache is perfect for it and also the most efficient for our page generation scripts).
114
103
10. These files are in the correct flat format for our page generation scripts, so copy these files and paste them to `src/data/method/` folder for the target language, in this case `src/data/method/fi`
115
-
11. Validate that your changes work TODO
104
+
11. Validate that your changes work with `npm test`
116
105
12. Commit your code and make a pull request.
117
106
13. After your pull request has been merged, remember to pull changes so that your local branch is deleted, too. (Make sure you don't leave locally any old files under `.json-autotranslate-cache`.)
118
107
119
-
If you are planning to use automated translation services: Note that there are some languages that are supported by some of the translation services with local varieties. Check the documentation (https://github.com/leolabs/json-autotranslate) of supported automated translation services and how to see which languages they support.
120
-
121
-
122
-
## Repository structure
123
-
124
-
```
125
-
├── src/
126
-
│ ├── assets/ # APIOps Cycles logos and other core assets which you might need in your tooling or product
127
-
│ ├── data/method/ # The Method JSON files (structure, relationship, and guideline content)
128
-
│ ├── data/method/canvas/ # The Canvases included in the method as JSON files (also used by tools like Canvas Creator)
129
-
│ ├── snippets/ # Raw markdown files used for long content for resource docs (only essential extensions for the json files)
130
-
├── scripts/ # Utility scripts
131
-
└── package.json
132
-
```
133
-
134
-
## License
135
-
136
-
All content in this repository is provided under Apache 2 license for programmable use, the content and the design of the canvases is under the CC BY-SA 4.0 license unless noted otherwise.
137
-
APIOps and APIOps Cycles are trademarks owned by Osaango Oy (https://www.osaango.com). Permission is given to use them in connection with the method, for community purposes. Contact Osaango for partnerships, or sponsoring to support the method development. See method website for current partners (https://www.apiopscycles.com/)
108
+
If you are planning to use automated translation services: Note that there are some languages that are supported by some of the translation services with local varieties. Check the documentation (https://github.com/leolabs/json-autotranslate) of supported automated translation services and how to see which languages they support.
0 commit comments