Tool for consistent documentation generation (#810)

cs3org · Jun 9, 2020 · fa72def88033bf9d1d1da2843e26f67d4666b3b2
1 parent f57a621
commit fa72def88033bf9d1d1da2843e26f67d4666b3b2
Showing 63 changed files with 87 additions and 56 deletions.
diff --git a/docs/content/en/docs/Config/GRPC/Services/UserProvider/StorageProvider/_index.md b/docs/content/en/docs/Config/GRPC/Services/UserProvider/StorageProvider/_index.md
diff --git a/docs/content/en/docs/_index.md b/docs/content/en/docs/_index.md
@@ -8,8 +8,8 @@ menu:
     weight: 20
 ---
 
-This is the documentation for the Reva project. 
+This is the documentation for the Reva project.
 
-We recommend you to start reading the [Overview]({{< ref "docs/Overview" >}}).
+We recommend you to start reading the [Overview]({{< ref "docs/overview" >}}).
 
-If you find a typo or you want to contribute to the documentation go to [Contribution Guidelines]({{< ref "docs/Contribution Guidelines" >}}).
+If you find a typo or you want to contribute to the documentation go to [Contribution Guidelines]({{< ref "docs/contribution-guidelines" >}}).
diff --git a/...content/en/docs/Changelog/0.0.1/_index.md → ...content/en/docs/changelog/0.0.1/_index.md b/...content/en/docs/Changelog/0.0.1/_index.md → ...content/en/docs/changelog/0.0.1/_index.md
diff --git a/...content/en/docs/Changelog/0.1.0/_index.md → ...content/en/docs/changelog/0.1.0/_index.md b/...content/en/docs/Changelog/0.1.0/_index.md → ...content/en/docs/changelog/0.1.0/_index.md
diff --git a/docs/content/en/docs/Changelog/_index.md → docs/content/en/docs/changelog/_index.md b/docs/content/en/docs/Changelog/_index.md → docs/content/en/docs/changelog/_index.md
diff --git a/docs/content/en/docs/Concepts/_index.md → docs/content/en/docs/concepts/_index.md b/docs/content/en/docs/Concepts/_index.md → docs/content/en/docs/concepts/_index.md
@@ -1,7 +1,7 @@
 ---
 title: "Concepts"
 linkTitle: "Concepts"
-weight: 4
+weight: 10
 description: >
   What does your user need to understand about your project in order to use it - or potentially contribute to it? 
 ---

diff --git a/docs/content/en/docs/Concepts/storages.md → docs/content/en/docs/concepts/storages.md b/docs/content/en/docs/Concepts/storages.md → docs/content/en/docs/concepts/storages.md
diff --git a/docs/content/en/docs/Config/_index.md → docs/content/en/docs/config/_index.md b/docs/content/en/docs/Config/_index.md → docs/content/en/docs/config/_index.md
@@ -1,7 +1,7 @@
 ---
 title: "Configuration"
 linkTitle: "Configuration"
-weight: 3
+weight: 10
 description: >
   Configuration reference for all Reva directives
 ---

diff --git a/docs/content/en/docs/Config/core.md → docs/content/en/docs/config/core.md b/docs/content/en/docs/Config/core.md → docs/content/en/docs/config/core.md
@@ -1,7 +1,7 @@
 ---
 title: "Core"
 linkTitle: "Core"
-weight: 1
+weight: 5
 description: >
   Directives to tweak the running Reva process.
 ---

diff --git a/docs/content/en/docs/Config/GRPC/_index.md → docs/content/en/docs/config/grpc/_index.md b/docs/content/en/docs/Config/GRPC/_index.md → docs/content/en/docs/config/grpc/_index.md
@@ -1,7 +1,7 @@
 ---
 title: "GRPC"
 linkTitle: "GRPC"
-weight: 11
+weight: 10
 description: >
   Configuration reference for GRPC
 ---

diff --git a/...n/docs/Config/GRPC/Interceptors/_index.md → ...n/docs/config/grpc/interceptors/_index.md b/...n/docs/Config/GRPC/Interceptors/_index.md → ...n/docs/config/grpc/interceptors/_index.md
diff --git a/...s/Config/GRPC/Interceptors/Auth/_index.md → ...s/config/grpc/interceptors/auth/_index.md b/...s/Config/GRPC/Interceptors/Auth/_index.md → ...s/config/grpc/interceptors/auth/_index.md
diff --git a/...nt/en/docs/Config/GRPC/Services/_index.md → ...nt/en/docs/config/grpc/services/_index.md b/...nt/en/docs/Config/GRPC/Services/_index.md → ...nt/en/docs/config/grpc/services/_index.md
diff --git a/...nfig/GRPC/Services/AuthProvider/_index.md → ...nfig/grpc/services/authprovider/_index.md b/...nfig/GRPC/Services/AuthProvider/_index.md → ...nfig/grpc/services/authprovider/_index.md
diff --git a/...nfig/GRPC/Services/AuthRegistry/_index.md → ...nfig/grpc/services/authregistry/_index.md b/...nfig/GRPC/Services/AuthRegistry/_index.md → ...nfig/grpc/services/authregistry/_index.md
diff --git a/...cs/Config/GRPC/Services/Gateway/_index.md → ...cs/config/grpc/services/gateway/_index.md b/...cs/Config/GRPC/Services/Gateway/_index.md → ...cs/config/grpc/services/gateway/_index.md
diff --git a/...Config/GRPC/Services/HelloWorld/_index.md → ...config/grpc/services/helloworld/_index.md b/...Config/GRPC/Services/HelloWorld/_index.md → ...config/grpc/services/helloworld/_index.md
diff --git a/...g/GRPC/Services/StorageProvider/_index.md → ...g/grpc/services/storageprovider/_index.md b/...g/GRPC/Services/StorageProvider/_index.md → ...g/grpc/services/storageprovider/_index.md
diff --git a/...g/GRPC/Services/StorageRegistry/_index.md → ...g/grpc/services/storageregistry/_index.md b/...g/GRPC/Services/StorageRegistry/_index.md → ...g/grpc/services/storageregistry/_index.md
diff --git a/...nfig/GRPC/Services/UserProvider/_index.md → ...nfig/grpc/services/userprovider/_index.md b/...nfig/GRPC/Services/UserProvider/_index.md → ...nfig/grpc/services/userprovider/_index.md
diff --git a/...nfig/GRPC/Services/UserRegistry/_index.md → ...nfig/grpc/services/userregistry/_index.md b/...nfig/GRPC/Services/UserRegistry/_index.md → ...nfig/grpc/services/userregistry/_index.md
diff --git a/...GRPC/Services/UserShareProvider/_index.md → ...grpc/services/usershareprovider/_index.md b/...GRPC/Services/UserShareProvider/_index.md → ...grpc/services/usershareprovider/_index.md
diff --git a/docs/content/en/docs/Config/HTTP/_index.md → docs/content/en/docs/config/http/_index.md b/docs/content/en/docs/Config/HTTP/_index.md → docs/content/en/docs/config/http/_index.md
@@ -7,7 +7,7 @@ description: >
 ---
 
 {{% dir name="network" type="string" default="tcp" %}}
-Specifies the network type. 
+Specifies the network type.
 {{< highlight toml >}}
 [http]
 network = "tcp"

diff --git a/...en/docs/Config/HTTP/Middlewares/_index.md → ...en/docs/config/http/middlewares/_index.md b/...en/docs/Config/HTTP/Middlewares/_index.md → ...en/docs/config/http/middlewares/_index.md
diff --git a/...cs/Config/HTTP/Middlewares/Auth/_index.md → ...cs/config/http/middlewares/auth/_index.md b/...cs/Config/HTTP/Middlewares/Auth/_index.md → ...cs/config/http/middlewares/auth/_index.md
diff --git a/...cs/Config/HTTP/Middlewares/CORS/_index.md → ...cs/config/http/middlewares/cors/_index.md b/...cs/Config/HTTP/Middlewares/CORS/_index.md → ...cs/config/http/middlewares/cors/_index.md
diff --git a/...nt/en/docs/Config/HTTP/Services/_index.md → ...nt/en/docs/config/http/services/_index.md b/...nt/en/docs/Config/HTTP/Services/_index.md → ...nt/en/docs/config/http/services/_index.md
diff --git a/...onfig/HTTP/Services/DataGateway/_index.md → ...onfig/http/services/datagateway/_index.md b/...onfig/HTTP/Services/DataGateway/_index.md → ...onfig/http/services/datagateway/_index.md
diff --git a/...nfig/HTTP/Services/DataProvider/_index.md → ...nfig/http/services/dataprovider/_index.md b/...nfig/HTTP/Services/DataProvider/_index.md → ...nfig/http/services/dataprovider/_index.md
diff --git a/...Config/HTTP/Services/HelloWorld/_index.md → ...config/http/services/helloworld/_index.md b/...Config/HTTP/Services/HelloWorld/_index.md → ...config/http/services/helloworld/_index.md
diff --git a/...ocs/Config/HTTP/Services/Mentix/_index.md → ...ocs/config/http/services/mentix/_index.md b/...ocs/Config/HTTP/Services/Mentix/_index.md → ...ocs/config/http/services/mentix/_index.md
diff --git a/...nfig/HTTP/Services/Mentix/GOCDB/_index.md → ...nfig/http/services/mentix/gocdb/_index.md b/...nfig/HTTP/Services/Mentix/GOCDB/_index.md → ...nfig/http/services/mentix/gocdb/_index.md
diff --git a/...HTTP/Services/Mentix/PromFileSD/_index.md → ...http/services/mentix/promfilesd/_index.md b/...HTTP/Services/Mentix/PromFileSD/_index.md → ...http/services/mentix/promfilesd/_index.md
diff --git a/...fig/HTTP/Services/Mentix/WebAPI/_index.md → ...fig/http/services/mentix/webapi/_index.md b/...fig/HTTP/Services/Mentix/WebAPI/_index.md → ...fig/http/services/mentix/webapi/_index.md
diff --git a/...fig/HTTP/Services/MeshDirectory/_index.md → ...fig/http/services/meshdirectory/_index.md b/...fig/HTTP/Services/MeshDirectory/_index.md → ...fig/http/services/meshdirectory/_index.md
diff --git a/...nfig/HTTP/Services/OIDCProvider/_index.md → ...nfig/http/services/oidcprovider/_index.md b/...nfig/HTTP/Services/OIDCProvider/_index.md → ...nfig/http/services/oidcprovider/_index.md
diff --git a/...s/Config/HTTP/Services/ownCloud/_index.md → ...s/config/http/services/owncloud/_index.md b/...s/Config/HTTP/Services/ownCloud/_index.md → ...s/config/http/services/owncloud/_index.md
diff --git a/...ig/HTTP/Services/ownCloud/OCDAV/_index.md → ...ig/http/services/owncloud/ocdav/_index.md b/...ig/HTTP/Services/ownCloud/OCDAV/_index.md → ...ig/http/services/owncloud/ocdav/_index.md
diff --git a/...nfig/HTTP/Services/ownCloud/OCS/_index.md → ...nfig/http/services/owncloud/ocs/_index.md b/...nfig/HTTP/Services/ownCloud/OCS/_index.md → ...nfig/http/services/owncloud/ocs/_index.md
diff --git a/...Config/HTTP/Services/Prometheus/_index.md → ...config/http/services/prometheus/_index.md b/...Config/HTTP/Services/Prometheus/_index.md → ...config/http/services/prometheus/_index.md
diff --git a/.../Config/HTTP/Services/WellKnown/_index.md → .../config/http/services/wellknown/_index.md b/.../Config/HTTP/Services/WellKnown/_index.md → .../config/http/services/wellknown/_index.md
diff --git a/docs/content/en/docs/Config/log.md → docs/content/en/docs/config/log.md b/docs/content/en/docs/Config/log.md → docs/content/en/docs/config/log.md
@@ -1,7 +1,7 @@
 ---
 title: "Log"
 linkTitle: "Log"
-weight: 2
+weight: 5
 description: >
   Directives to configure the logging system
 ---

diff --git a/docs/content/en/docs/config/packages/_index.md b/docs/content/en/docs/config/packages/_index.md
@@ -0,0 +1,7 @@
+---
+title: "Packages"
+linkTitle: "Packages"
+weight: 10
+description: >
+  Configuration reference for utility packages
+---
diff --git a/...en/docs/Contribution guidelines/_index.md → ...en/docs/contribution-guidelines/_index.md b/...en/docs/Contribution guidelines/_index.md → ...en/docs/contribution-guidelines/_index.md
diff --git a/...content/en/docs/Getting started/_index.md → ...content/en/docs/getting-started/_index.md b/...content/en/docs/Getting started/_index.md → ...content/en/docs/getting-started/_index.md
diff --git a/...n/docs/Getting started/beginners-guide.md → ...n/docs/getting-started/beginners-guide.md b/...n/docs/Getting started/beginners-guide.md → ...n/docs/getting-started/beginners-guide.md
@@ -8,7 +8,7 @@ description: >
 
 This guide gives a basic introduction to Reva and describes some simple tasks that can be done with it.
 This guide assumes that Reva is already installed on the reader's machine.
-If this isn't the case refer to [Install Reva]({{< relref "docs/Getting Started/install-reva" >}})
+If this isn't the case refer to [Install Reva]({{< relref "docs/getting-started/install-reva" >}})
 
 This guide describes how to start and stop the **Reva daemon (revad)**, and reload its configuration, explains the structure of the configuration
 file and describes how to set up revad to serve some basic services.
@@ -44,7 +44,7 @@ If you don't specify the pid file with the -p flag Reva will create one in the O
 You can always obtain the location of the file from the logs
 {{% /alert %}}
 
-Once revad is started, it can be controlled by invoking the executable with the -s parameter. Use the following syntax: 
+Once revad is started, it can be controlled by invoking the executable with the -s parameter. Use the following syntax:
 
 ```
 revad -s <signal> -p /var/tmp/revad.pid
@@ -56,7 +56,7 @@ Where signal may be one of the following:
 * quit — graceful shutdown
 * reload — reloading the configuration file (forks a new process)
 
- For example, to stop revad gracefully, the following command can be executed: 
+ For example, to stop revad gracefully, the following command can be executed:
 
 ```
 revad -s quit -p /var/tmp/revad.pid
@@ -66,27 +66,27 @@ revad -s quit -p /var/tmp/revad.pid
 This command should be executed under the same user that started the server.
 {{% /alert %}}
 
-Changes made in the configuration file will not be applied until the command to reload configuration is sent to revad. Let's reload the config: 
+Changes made in the configuration file will not be applied until the command to reload configuration is sent to revad. Let's reload the config:
 
 ```
 revad -s reload -p /var/tmp/revad.pid
 ```
 
 Once the main process receives the signal to reload configuration, it checks the syntax validity of the new configuration file and tries to apply the configuration provided in it. If this is a success, the main process forks a new process. The new forked process will gracefully kill the parent process. During a period of time until all ongoing requests are served, both processes will share the same network socket, the old parent process will serve ongoing requests and the new process will serve only new requests. No requests are dropped during the reload. If the provided configuration is invalid, the forked process will die and the master process will continue serving requests.
 
-A signal may also be sent to the revad process with the help of Unix tools such as the *kill* utility. In this case a signal is sent directly to a process with a given process ID. The process ID of the revad master process is written to the pid file, as configured with the *-s* flag. For example, if the master process ID is 1610, to send the QUIT signal resulting in revad’s graceful shutdown, execute: 
+A signal may also be sent to the revad process with the help of Unix tools such as the *kill* utility. In this case a signal is sent directly to a process with a given process ID. The process ID of the revad master process is written to the pid file, as configured with the *-s* flag. For example, if the master process ID is 1610, to send the QUIT signal resulting in revad’s graceful shutdown, execute:
 
 ```
 kill -s QUIT 1610
 ```
 
-For getting the list of all running revad processes, the *ps* utility may be used, for example, in the following way: 
+For getting the list of all running revad processes, the *ps* utility may be used, for example, in the following way:
 
 ```
 ps -ax | grep revad
 ```
 
-For more information on sending signals to revad, see [Controlling Reva]({{< ref "docs/Getting Started/control-reva" >}}).
+For more information on sending signals to revad, see [Controlling Reva]({{< ref "docs/getting-started/control-reva" >}}).
 
 ## Running your first service
 
@@ -132,5 +132,4 @@ Let's analyze the output:
 
 **Congratulations, you've run your first Reva service!**
 
-You can head to [Tutorials]({{< ref "docs/Tutorials" >}}) to find more advanced guides.
-
+You can head to [Tutorials]({{< ref "docs/tutorials" >}}) to find more advanced guides.
diff --git a/...ent/en/docs/Getting started/build-reva.md → ...ent/en/docs/getting-started/build-reva.md b/...ent/en/docs/Getting started/build-reva.md → ...ent/en/docs/getting-started/build-reva.md
diff --git a/...t/en/docs/Getting started/control-reva.md → ...t/en/docs/getting-started/control-reva.md b/...t/en/docs/Getting started/control-reva.md → ...t/en/docs/getting-started/control-reva.md
diff --git a/...t/en/docs/Getting started/install-reva.md → ...t/en/docs/getting-started/install-reva.md b/...t/en/docs/Getting started/install-reva.md → ...t/en/docs/getting-started/install-reva.md
diff --git a/docs/content/en/docs/Overview/_index.md → docs/content/en/docs/overview/_index.md b/docs/content/en/docs/Overview/_index.md → docs/content/en/docs/overview/_index.md
@@ -11,12 +11,12 @@ description: >
 Reva is an open source platform developed in the Go programming language with two purposes:
 
 1. As an interoperability platform to link platforms with the storage and application providers.
-2. As the reference implementation of the CS3APIS. 
+2. As the reference implementation of the CS3APIS.
 
 #### The problem  we try to solve
 
 Today any cloud sync and share provider either closed-source (Dropbox, Google Drive, ...) or open source (ownCloud, Seafile, ...) have their own catalogue
-of integrations with many applicaition providers. The pitty about these integrations is that they are ad-hoc to the cloud vendor, making it impossible to port 
+of integrations with many applicaition providers. The pitty about these integrations is that they are ad-hoc to the cloud vendor, making it impossible to port
 anywhere else.
 
 {{< imgproc "overview.png" Fit "800x600" >}}
@@ -25,8 +25,8 @@ anywhere else.
 #### The goal
 
 Our ultimate goal is that any open source project and software vendor that provides either storage or applications to an EFSS platform
-will adopt the CS3APIS as the facto standard way to collaborate. Having all the partners using the same APIs will enable all of us for a new dimension 
-of portability of applications across vendors. 
+will adopt the CS3APIS as the facto standard way to collaborate. Having all the partners using the same APIs will enable all of us for a new dimension
+of portability of applications across vendors.
 
 {{< imgproc "final.png" Fit "800x600">}}
 {{< /imgproc >}}
@@ -38,7 +38,7 @@ In the mean time, we have another approach to make these systems talk to each ot
 #### The approach with Reva
 
 The motivation is to move out the ad-hoc APIs from the sync and share platform to Reva. As Reva is a vendor-neutral and open source
-project we expect that many institutions and application providers will contribute with their ad-hoc APIs to Reva, creating an inter-operability platform 
+project we expect that many institutions and application providers will contribute with their ad-hoc APIs to Reva, creating an inter-operability platform
 that could potencially connect to an eco-system of applications and storage catalogs as never seen before.
 
 The platform acts as middleware component in your current infrastructure, and by connecting your cloud to Reva you gain access
@@ -56,12 +56,11 @@ How many times have you been using an app that you lost when you switched cloud
 and runs alongside your infrastructure.
 
 * **What is it *not yet* good for?**: Reva is still very young to be used in production. We are working hard to reach a stable version soon with decent integrations to storage
-and applications. We don't want to re-invent the wheel so we have in mind that Reva will provide integrations with [rclone](https://rclone.org/) for multiple-storage support and with other protocols out there like [WOPI](https://wopi.readthedocs.io/en/latest/) 
+and applications. We don't want to re-invent the wheel so we have in mind that Reva will provide integrations with [rclone](https://rclone.org/) for multiple-storage support and with other protocols out there like [WOPI](https://wopi.readthedocs.io/en/latest/)
 , [Learning Tools Interoperability](https://www.imsglobal.org/activity/learning-tools-interoperability) and
 [OpenCloudMesh](https://rawgit.com/GEANT/OCM-API/v1/docs.html) to enable seamless collaboration.
 
 ## Where should I go next?
 
-* [Getting Started]({{< ref "docs/Getting Started" >}}): Get started with the project
-* [Concepts]({{< ref "docs/Concepts" >}}): Deep-dive into the conceps behind Reva 
-
+* [Getting Started]({{< ref "docs/getting-started" >}}): Get started with the project
+* [Concepts]({{< ref "docs/concepts" >}}): Deep-dive into the conceps behind Reva
diff --git a/docs/content/en/docs/Overview/final.drawio → docs/content/en/docs/overview/final.drawio b/docs/content/en/docs/Overview/final.drawio → docs/content/en/docs/overview/final.drawio
diff --git a/docs/content/en/docs/Overview/final.png → docs/content/en/docs/overview/final.png b/docs/content/en/docs/Overview/final.png → docs/content/en/docs/overview/final.png
diff --git a/.../content/en/docs/Overview/overview.drawio → .../content/en/docs/overview/overview.drawio b/.../content/en/docs/Overview/overview.drawio → .../content/en/docs/overview/overview.drawio
diff --git a/docs/content/en/docs/Overview/overview.png → docs/content/en/docs/overview/overview.png b/docs/content/en/docs/Overview/overview.png → docs/content/en/docs/overview/overview.png
diff --git a/docs/content/en/docs/Overview/reva.drawio → docs/content/en/docs/overview/reva.drawio b/docs/content/en/docs/Overview/reva.drawio → docs/content/en/docs/overview/reva.drawio
diff --git a/docs/content/en/docs/Overview/reva.png → docs/content/en/docs/overview/reva.png b/docs/content/en/docs/Overview/reva.png → docs/content/en/docs/overview/reva.png
diff --git a/docs/content/en/docs/Tutorials/_index.md → docs/content/en/docs/tutorials/_i b/docs/content/en/docs/Tutorials/_index.md → docs/content/en/docs/tutorials/_i