Enable read-the-docs based user guides (winery#482)

OpenTOSCA · May 19, 2020 · aaadb68 · aaadb68
1 parent ee14eb8
commit aaadb68
Show file tree

Hide file tree

Showing 239 changed files with 2,000 additions and 2,354 deletions.
diff --git a/.idea/codeStyles/codeStyleConfig.xml b/.idea/codeStyles/codeStyleConfig.xml
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,6 @@
+build:
+  image: latest
+
+python:
+  version: 3.7
+  requirements_file: docs/requirements.txt
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,2 @@
+.vscode
+_build
diff --git a/docs/DeveloperGuide.html b/docs/DeveloperGuide.html
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,31 @@
+#  Copyright (c) 2020 Contributors to the Eclipse Foundation
+# 
+#  See the NOTICE file(s) distributed with this work for additional
+#  information regarding copyright ownership.
+# 
+#  This program and the accompanying materials are made available under the
+#  terms of the Eclipse Public License 2.0 which is available at
+#  http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
+#  which is available at https://www.apache.org/licenses/LICENSE-2.0.
+# 
+#  SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,23 @@
+<!---~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ Copyright (c) 2020 Contributors to the Eclipse Foundation
+  ~
+  ~ See the NOTICE file(s) distributed with this work for additional
+  ~ information regarding copyright ownership.
+  ~
+  ~ This program and the accompanying materials are made available under the
+  ~ terms of the Eclipse Public License 2.0 which is available at
+  ~ http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
+  ~ which is available at https://www.apache.org/licenses/LICENSE-2.0.
+  ~
+  ~ SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
+
+
+# Eclipse Winery Documentation
+
+## Build
+
+```
+pip install -r requirements.txt
+make.bat html
+```
diff --git a/docs/SUPPORT.md b/docs/SUPPORT.md
diff --git a/docs/ToolChain.html b/docs/ToolChain.html
diff --git a/docs/UserGuide.html b/docs/UserGuide.html
diff --git a/docs/tosca/yaml/Converter.md → docs/_legacy/Converter.md b/docs/tosca/yaml/Converter.md → docs/_legacy/Converter.md
diff --git a/...AndComponentExtractionForChefCookbooks.md → ...AndComponentExtractionForChefCookbooks.md b/...AndComponentExtractionForChefCookbooks.md → ...AndComponentExtractionForChefCookbooks.md
diff --git a/docs/user/DASpecification.md → docs/_legacy/DASpecification.md b/docs/user/DASpecification.md → docs/_legacy/DASpecification.md
diff --git a/docs/user/DeployableComponentsUsage.md → docs/_legacy/DeployableComponentsUsage.md b/docs/user/DeployableComponentsUsage.md → docs/_legacy/DeployableComponentsUsage.md
diff --git a/docs/tosca/yaml/ModelChangesAndExtensions.md → docs/_legacy/ModelChangesAndExtensions.md b/docs/tosca/yaml/ModelChangesAndExtensions.md → docs/_legacy/ModelChangesAndExtensions.md
diff --git a/docs/dev/TOSCA-Management.md → docs/_legacy/TOSCA-Management.md b/docs/dev/TOSCA-Management.md → docs/_legacy/TOSCA-Management.md
@@ -8,7 +8,7 @@ system, this structure is also present in the angular app.
 Entry into the angular app is the `WineryRepositoryComponent`. It contains the standard header and the router outlet.
 All main routes are configured in the `WineryRepositoryRoutingModule` which is bootstrapped in the `WineryRepositoryModule`.
 
-![Angular Component Diagram](graphics/repositoryUiAngularComponentDiagram.png)
+![Angular Component Diagram](figures/repositoryUiAngularComponentDiagram.png)
 [source](repositoryUiAngularComponentDiagram.plantuml)
 
 ### Main Routes

diff --git a/docs/_config.yml → docs/_legacy/_config.yml b/docs/_config.yml → docs/_legacy/_config.yml
diff --git a/docs/dev/howtos/howto-angular.md → docs/_legacy/angular.md b/docs/dev/howtos/howto-angular.md → docs/_legacy/angular.md
@@ -1,28 +1,21 @@
-# Eclipse Winery Angular Apps
+# Winery's Angular Apps
 
-TODO: generisch für beide apps
-
-## Prerequisites
-1. Install [git](https://git-scm.com)
-2. Install and setup [Node.js](https://nodejs.org/en/) and [NPM](https://www.npmjs.com) which ships with Node.js
-3. **optional** Install the [Angular-CLI](https://cli.angular.io) globally. 
-
-### Backend
+## Backend
 The frontend assumes that the backend server is running on
 - the same host,
 - the same protocol,
 - the same port
 - and is reachable under the context `/winery`.
 
-#### Development
 If the frontend runs via npm on the development ports, the backend MUST be running at port `8080`.
 
 An example request to the backend, if it runs locally, looks like this: `http://localhost:8080/winery/servicetemplates`.
 
 
-### Topologymodeler
-During development, the repository UI depends on the development version of the topologymodeler. Therefore,
-you need to have both angular apps running with the local development server outlined below.
+## Topology Modeler
+
+During development, the repository UI depends on the development version of the topologymodeler.
+Therefore, you need to have both angular apps running with the local development server outlined below.
 
 Otherwise, the repository UI assumes that the topologymodeler runs on
 - the same host,
@@ -92,21 +85,3 @@ You can also set up a IntelliJ run configuration as outlined above. Instead of c
 ## Generate war files
 Execute `mvn package`.
 
-
-## Development Hints
-- [Exiting a for-each loop early](https://stackoverflow.com/a/2641374/6592788) 
-
-
-## License
-
-Copyright (c) 2017 Contributors to the Eclipse Foundation
-
-See the NOTICE file(s) distributed with this work for additional
-information regarding copyright ownership.
-
-This program and the accompanying materials are made available under the
-terms of the Eclipse Public License 2.0 which is available at
-http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
-which is available at https://www.apache.org/licenses/LICENSE-2.0.
-
-SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
diff --git a/docs/dev/building.md → docs/_legacy/building.md b/docs/dev/building.md → docs/_legacy/building.md
diff --git a/docs/dev/howtos/howto-repository.md → docs/_legacy/howto-repository.md b/docs/dev/howtos/howto-repository.md → docs/_legacy/howto-repository.md
@@ -1,6 +1,6 @@
 ## Working with the Repository
 
-![Repository Interfaces Inheritance](graphics/InheritanceOfInterfacesRelatedToTheRepository.png)  
+![Repository Interfaces Inheritance](figures/InheritanceOfInterfacesRelatedToTheRepository.png)  
 
 The general idea is to seperate the repository and the repository client.
 The repository itself is only accessed through the REST resources offered by `org.eclipse.winery.repository.rest`.

diff --git a/docs/dev/howtos/howto-test-repository.md → docs/_legacy/howto-test-repository.md b/docs/dev/howtos/howto-test-repository.md → docs/_legacy/howto-test-repository.md
diff --git a/...er/graphics/modeling/3-AddNewNodeType.PNG → docs/_legacy/modeling/3-AddNewNodeType.PNG b/...er/graphics/modeling/3-AddNewNodeType.PNG → docs/_legacy/modeling/3-AddNewNodeType.PNG
diff --git a/...er/graphics/modeling/4-AddNewNodeType.PNG → docs/_legacy/modeling/4-AddNewNodeType.PNG b/...er/graphics/modeling/4-AddNewNodeType.PNG → docs/_legacy/modeling/4-AddNewNodeType.PNG
diff --git a/...odeling/5-AddNewNodeType-AddInterface.PNG → ...odeling/5-AddNewNodeType-AddInterface.PNG b/...odeling/5-AddNewNodeType-AddInterface.PNG → ...odeling/5-AddNewNodeType-AddInterface.PNG
diff --git a/...odeling/6-AddNewNodeType-AddInterface.PNG → ...odeling/6-AddNewNodeType-AddInterface.PNG b/...odeling/6-AddNewNodeType-AddInterface.PNG → ...odeling/6-AddNewNodeType-AddInterface.PNG
diff --git a/...ositoryUiAngularComponentDiagram.plantuml → ...ositoryUiAngularComponentDiagram.plantuml b/...ositoryUiAngularComponentDiagram.plantuml → ...ositoryUiAngularComponentDiagram.plantuml
diff --git a/...s/repositoryUiAngularComponentDiagram.png → ...y/repositoryUiAngularComponentDiagram.png b/...s/repositoryUiAngularComponentDiagram.png → ...y/repositoryUiAngularComponentDiagram.png
diff --git a/docs/user/TopologyCompletionTutorial.md → docs/_legacy/topology-completion-tutorial.md b/docs/user/TopologyCompletionTutorial.md → docs/_legacy/topology-completion-tutorial.md
diff --git a/docs/dev/troubleshootings.md → docs/_legacy/troubleshootings.md b/docs/dev/troubleshootings.md → docs/_legacy/troubleshootings.md
diff --git a/...letion/tutorial/Example_Topology_TC_1.png → ...legacy/tutorial/Example_Topology_TC_1.png b/...letion/tutorial/Example_Topology_TC_1.png → ...legacy/tutorial/Example_Topology_TC_1.png
diff --git a/...letion/tutorial/Example_Topology_TC_2.png → ...legacy/tutorial/Example_Topology_TC_2.png b/...letion/tutorial/Example_Topology_TC_2.png → ...legacy/tutorial/Example_Topology_TC_2.png
diff --git a/...phics/completion/tutorial/Import_Repo.png → docs/_legacy/tutorial/Import_Repo.png b/...phics/completion/tutorial/Import_Repo.png → docs/_legacy/tutorial/Import_Repo.png
diff --git a/...completion/tutorial/NodeType_Overview.png → docs/_legacy/tutorial/NodeType_Overview.png b/...completion/tutorial/NodeType_Overview.png → docs/_legacy/tutorial/NodeType_Overview.png
diff --git a/...letion/tutorial/Open_Topology_Modeler.png → ...legacy/tutorial/Open_Topology_Modeler.png b/...letion/tutorial/Open_Topology_Modeler.png → ...legacy/tutorial/Open_Topology_Modeler.png
diff --git a/...n/tutorial/Requirement_Types_Overview.png → ...y/tutorial/Requirement_Types_Overview.png b/...n/tutorial/Requirement_Types_Overview.png → ...y/tutorial/Requirement_Types_Overview.png
diff --git a/...completion/tutorial/Tc_dialog_example.png → docs/_legacy/tutorial/Tc_dialog_example.png b/...completion/tutorial/Tc_dialog_example.png → docs/_legacy/tutorial/Tc_dialog_example.png
diff --git a/...s/completion/tutorial/Tc_step_by_step.png → docs/_legacy/tutorial/Tc_step_by_step.png b/...s/completion/tutorial/Tc_step_by_step.png → docs/_legacy/tutorial/Tc_step_by_step.png
diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep
diff --git a/docs/adr/0002-filesystem-folder-structure-using-type-namespace-id-structure.md b/docs/adr/0002-filesystem-folder-structure-using-type-namespace-id-structure.md
@@ -1,6 +1,6 @@
 # File system folder structure using type-namespace-id structure
 
-Winery's data is stored in a a file system [ADR-0001](0001-use-filesystem-as-backend).
+Winery's data is stored in a a file system [ADR-0001](0001-use-filesystem-as-backend.md).
 The contents of the repository should be
 
 - human readable
@@ -15,7 +15,7 @@ The contents of the repository should be
 
 *Chosen Alternative: Folders subdivided in type-namespace-id*
 
-The final file system layout itself is documented at [RepositoryLayout](../dev/RepositoryLayout).
+The final file system layout itself is documented at [RepositoryLayout](../dev/repository-layout.md).
 
 ### human readable
 

diff --git a/docs/adr/0003-double-encoded-urls.md b/docs/adr/0003-double-encoded-urls.md
@@ -3,7 +3,7 @@
 URLs should be human-readable, slashes are not allowed.
 Encoded slahes are not enabled as default due to security reasons.
 
-More information about encoding is available at [dev/Encoding.md](dev/Encoding).
+More information about encoding is available at [dev/Encoding.md](../dev/encoding.md).
 
 ## Considered Alternatives
 

diff --git a/docs/adr/0015-copy-source-to-files.md b/docs/adr/0015-copy-source-to-files.md
@@ -31,4 +31,4 @@ Forces:
 * `-` Needs a runtime/compiler
 * `-` See [ADR-0014]
 
-  [ADR-0014]: (0014-use-eclipse-orion-as-editor.md)
+[ADR-0014]: 0014-use-eclipse-orion-as-editor.md
diff --git a/docs/adr/index.md b/docs/adr/index.md
@@ -1,3 +1,18 @@
+<!---~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ Copyright (c) 2020 Contributors to the Eclipse Foundation
+  ~
+  ~ See the NOTICE file(s) distributed with this work for additional
+  ~ information regarding copyright ownership.
+  ~
+  ~ This program and the accompanying materials are made available under the
+  ~ terms of the Eclipse Public License 2.0 which is available at
+  ~ http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
+  ~ which is available at https://www.apache.org/licenses/LICENSE-2.0.
+  ~
+  ~ SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
+
+
 # Architectural Decision Log
 
 This lists the architectural decisions for Eclipse Winery.
@@ -38,5 +53,5 @@ This lists the architectural decisions for Eclipse Winery.
 
 <!-- adrlogstop -->
 
-[template.md](template.md) contains the template.
+The [template.md](template.md) contains the MADR template.
 More information on MADR is available at <https://adr.github.io/madr/>.