Merge branch 'improve-docs' into 'dev'

Improve Foris JS documentation

See merge request turris/reforis/foris-js!190

docs/components/Logo.js

@@ -0,0 +1,36 @@
+import React from "react";
+import PropTypes from "prop-types";
+import Styled from "rsg-components/Styled";
+import logo from "./logo.svg";
+
+const styles = ({ fontFamily }) => ({
+    logo: {
+        display: "flex",
+        alignItems: "center",
+        margin: 0,
+        fontFamily: fontFamily.base,
+        fontSize: 18,
+        fontWeight: "normal",
+    },
+    image: {
+        height: "1.3em",
+        marginLeft: "-0.2em",
+        marginRight: "0.2em",
+    },
+});
+
+export function LogoRenderer({ classes, children }) {
+    return (
+        <h1 className={classes.logo}>
+            <img className={classes.image} src={logo} alt="React logo" />
+            {children}
+        </h1>
+    );
+}
+
+LogoRenderer.propTypes = {
+    classes: PropTypes.object.isRequired,
+    children: PropTypes.node,
+};
+
+export default Styled(styles)(LogoRenderer);

docs/components/logo.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="1000">
+    <path d="M288.258 240.0394L717.5586-.44c.803 62.277-1.8207 124.502-1.4996 186.7266 1.8208 7.6343-7.2288 10.1966-12.102 13.4908L286.4375 432.1518l1.8206-192.1124zm2.284 277.645L711 278.3176l-.8416 192.7742L457.357 614.514l-1.842 289.03-167.7097 95.8926 2.7365-481.753z"/>
+</svg>

docs/development.md

@@ -1,15 +1,15 @@
-Sooner or later you will face with situation when you want/need to make some
-changes in the library. Then the most important tool for you it's
+Sooner or later, you will face with situation when you want/need to make some
+changes in the library. Then the most important tool for you it's the
 [`npm link`](https://docs.npmjs.com/cli/link).
 
-Please, notice that it will not work if you link library just from root of the
-repo. It happens due to location of sources `./src`. You need to pack library
-first `make pack` and then link it from `./dist` directory.
+Please, notice that it will not work if you link the library just from the root
+of the repo. It happens due to the location of sources `./src`. You need to pack
+the library first, `make pack` and then link it from the `./dist` directory.
 
-Yeah it's not such comfortable solution for development. But it can fixed by
-writing small script similar as `make pack` but with linking every file and
-directory from `./src` to the some directory and linking then from it. Notice
-that you need to link `package.json` and `package-lock.json` as well.
+Yeah, it's not such a comfortable solution for development. But it can be fixed
+by writing a small script similar to making a pack but by linking every file and
+directory from `./src` to the same directory and linking then from it. Notice
+that you need to link a `package.json` and a `package-lock.json` as well.
 
 So step by step:
 

docs/forisjs-npm.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="500" height="500" fill="white">
+    <path d="M49.5 171.722222222222h400v133.333333333333h-200v22.222222222223h-88.888888888889v-22.222222222223H49.5V171.722222222222zm22.222222222222 111.111111111111h44.444444444445v-66.666666666667h22.222222222222v66.666666666667h22.222222222222v-88.888888888889H71.722222222222v88.888888888889zm111.111111111111-88.888888888889v111.111111111111h44.444444444445v-22.222222222222h44.444444444444v-88.888888888889h-88.888888888889zm44.444444444445 22.222222222222H249.5v44.444444444445h-22.222222222222v-44.444444444445zm66.666666666666-22.222222222222v88.888888888889h44.444444444445v-66.666666666667h22.222222222222v66.666666666667h22.222222222222v-66.666666666667h22.222222222222v66.666666666667h22.222222222223v-88.888888888889H293.944444444444z" fill="#cb3837" />
+    <path d="M71.722222222222 282.833333333333h44.444444444444v-66.666666666667h22.222222222223v66.666666666667h22.222222222222v-88.888888888889H71.722222222222zm111.111111111111-88.888888888889v111.111111111111h44.444444444444v-22.222222222222h44.444444444445v-88.888888888889h-88.888888888889zM249.5 260.611111111111h-22.222222222223v-44.444444444445H249.5v44.444444444445zm44.444444444444-66.666666666667v88.888888888889h44.444444444444v-66.666666666667h22.222222222223v66.666666666667h22.222222222222v-66.666666666667h22.222222222222v66.666666666667h22.222222222222v-88.888888888889z" />
+</svg>

docs/intro.md

@@ -1,6 +0,0 @@
-Foris JS library is set of components and utils for Foris JS application and
-plugins.
-
-Please notice that all of these components or utils are used in reForis and
-plugins. If you like to study by example I would recommend to full-text search
-these repos.

docs/introduction.md

@@ -0,0 +1,37 @@
+Welcome! This is the official documentation for Foris JS.
+
+## What Foris JS is
+
+Foris JS library is a set of components and utils for reForis application and
+plugins.
+
+Please notice that all of these components or utils are used in reForis and
+plugins. If you want to study them by example, I recommend you to full-text
+search those repositories.
+
+# Installation
+
+## Prerequisites
+
+Please make sure that [Node.js](https://nodejs.org/en/) is installed on your
+system.
+
+The current Long Term Support (LTS) release is an ideal starting point, see
+[here](https://github.com/nodejs/Release#release-schedule).
+
+## Installation
+
+To install the latest release:
+
+```plain
+npm install foris
+```
+
+To install a specific version:
+
+```plain
+npm install foris@version
+```
+
+<a target="_blank" href="https://www.npmjs.com/package/foris">Check
+on<img width="100px" src="./docs/forisjs-npm.svg"></a>

package.json

@@ -1,7 +1,7 @@
 {
     "name": "foris",
     "version": "5.4.1",
-    "description": "Set of components and utils for Foris and its plugins.",
+    "description": "Foris JS library is a set of components and utils for reForis application and plugins.",
     "author": "CZ.NIC, z.s.p.o.",
     "repository": {
         "type": "git",

src/bootstrap/Switch.md

@@ -0,0 +1,5 @@
+Switch example:
+
+```js
+<Switch label="Enable Switch" helpText="Toggle that switch!" />
+```

styleguide.config.js

@@ -1,39 +1,56 @@
 /*
- * Copyright (C) 2019 CZ.NIC z.s.p.o. (http://www.nic.cz/)
+ * Copyright (C) 2019-2022 CZ.NIC z.s.p.o. (https://www.nic.cz/)
  *
  * This is free software, licensed under the GNU General Public License v3.
  * See /LICENSE for more information.
  */
-
 const path = require("path");
+const pjson = require("./package.json");
 
 module.exports = {
-    title: "Foris JS docs",
+    title: "Foris JS Docs",
+    version: `v${pjson.version}`,
+    theme: {
+        color: {
+            link: "#0075a3",
+            linkHover: "#00a2e2",
+        },
+    },
+    tocMode: "collapse",
+    pagePerSection: true,
     sections: [
         {
-            name: "Foris JS",
-            content: "docs/intro.md",
+            name: "Introduction",
+            content: "docs/introduction.md",
         },
         {
-            name: "Development (Linking)",
+            name: "Development",
             content: "docs/development.md",
         },
         {
-            name: "Foris forms",
-            components: [
-                "src/form/components/ForisForm.js",
-                "src/form/components/alerts.js",
-                "src/form/components/SubmitButton.js",
+            name: "Components",
+            description: "Set of main components.",
+            sections: [
+                {
+                    name: "Foris forms",
+                    components: [
+                        "src/form/components/ForisForm.js",
+                        "src/form/components/alerts.js",
+                        "src/form/components/SubmitButton.js",
+                    ],
+                    exampleMode: "expand",
+                    usageMode: "expand",
+                },
+                {
+                    name: "Alert Context",
+                    components: ["src/alertContext/AlertContext.js"],
+                    exampleMode: "expand",
+                    usageMode: "expand",
+                },
             ],
-            exampleMode: "expand",
-            usageMode: "expand",
-        },
-        {
-            name: "Alert Context",
-            components: ["src/alertContext/AlertContext.js"],
-            exampleMode: "expand",
-            usageMode: "expand",
+            sectionDepth: 1,
         },
+
         {
             name: "Bootstrap components",
             description: "Set of bootstrap components.",
@@ -41,8 +58,12 @@ module.exports = {
             exampleMode: "expand",
             usageMode: "expand",
             ignore: ["src/bootstrap/constants.js"],
+            sectionDepth: 0,
         },
     ],
+    template: {
+        favicon: "/docs/components/logo.svg",
+    },
     require: [
         "babel-polyfill",
         path.join(__dirname, "src/testUtils/mockGlobals"),
@@ -55,6 +76,9 @@ module.exports = {
             "node_modules/@fortawesome/fontawesome-free/css/all.min.css"
         ),
     ],
+    styleguideComponents: {
+        LogoRenderer: path.join(__dirname, "docs/components/Logo"),
+    },
     webpackConfig: {
         module: {
             rules: [
@@ -73,5 +97,8 @@ module.exports = {
                 },
             ],
         },
+        devServer: {
+            publicPath: "/",
+        },
     },
 };