Merge pull request #12 from visto9259/add-docs

Added docs

.github/workflows/deploy-gh-pages.yml

@@ -0,0 +1,48 @@
+name: Build and Deploy to GitHub Pages
+
+defaults:
+  run:
+    shell: bash
+    working-directory: ./docs
+
+on:
+  push:
+    branches:
+      - 'master'
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
+
+
+jobs:
+  deploy:
+    name: Build and Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./docs
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: yarn
+          cache-dependency-path: docs/yarn.lock
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Build website
+        run: yarn build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./docs/build
+          # The following lines assign commit authorship to the official
+          # GH-Actions bot for deploys to `gh-pages` branch:
+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
+          # The GH actions bot is used by default if you didn't specify the two fields.
+          # You can swap them out with your own user credentials.
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

.github/workflows/test-deploy-gh-pages.yml

@@ -0,0 +1,29 @@
+name: Build GitHub Pages on PRs No Deploy
+
+defaults:
+  run:
+    shell: bash
+    working-directory: ./docs
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+  push:
+    paths:
+      - 'docs/**'
+jobs:
+  test-deploy:
+    name: Build GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: yarn
+          cache-dependency-path: docs/yarn.lock
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Test build website
+        run: yarn build

.gitignore

@@ -1,2 +1,4 @@
 vendor
-composer.lock
+composer.lock
+## PHPStorm files
+/.idea

README.md

@@ -1,6 +1,8 @@
->
-> This is work in progress to convert to Laminas
->
+[![Latest Stable Version](https://poser.pugx.org/lm-commons/lmc-admin/v/stable)](https://packagist.org/packages/lm-commons/lmc-admin)
+[![Total Downloads](http://poser.pugx.org/lm-commons/lmc-admin/downloads)](https://packagist.org/packages/lm-commons/lmc-admin)
+[![License](http://poser.pugx.org/lm-commons/lmc-admin/license)](https://packagist.org/packages/lm-commons/lmc-admin)
+[![PHP Version Require](http://poser.pugx.org/lm-commons/lmc-admin/require/php)](https://packagist.org/packages/lm-commons/lmc-admin)
+
 # LmcAdmin Module for Laminas Framework
 Created by [Jurian Sluiman](http://juriansluiman.nl) and [Martin Shwalbe](https://github.com/Hounddog).
 
@@ -15,12 +17,12 @@ If you do not want to use composer, clone this project (either as a git submodul
 ## Usage
 LmcAdmin allows you to create routes under a single parent "admin" route. You can also use it to enable navigation in your admin layout. Furthermore integration of [LmcRbacMvc](https://github.com/LM-Commons/LmcRbacMvc) is provided.
 
-The complete configuration is flexible, so you can update the zfcadmin parent route, its children, the navigation and all default provided view scripts. Read more in the [documentation](docs/1.Introduction.md) about usage and customization of LmcAdmin.
+The complete configuration is flexible, so you can update the zfcadmin parent route, its children, the navigation and all default provided view scripts. Read more in the [documentation](docs-old/1.Introduction.md) about usage and customization of LmcAdmin.
 
 ## Development
 LmcAdmin is currently under development. The authors feel LmcAdmin is stable enough for production versions and you can always fix your LmcAdmin version to a specific tag.
 
 ## Support
 
 - File issues at https://github.com/LM-Commons/LmcAdmin/issues.
-- Ask questions in the [LM-Commons gitter](https://gitter.im/LM-Commons/community) chat.
+- Ask questions in the [LM-Commons Slack](https://join.slack.com/t/lm-commons/shared_invite/zt-2gankt2wj-FTS45hp1W~JEj1tWvDsUHQ) chat.

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,55 @@
+# Documentation Website
+
+The Documentation Website is built using [Docusaurus](https://docusaurus.io/).
+
+If you want to make a contribution to the documentation, please follow these
+instructions:
+
+1. Fork the `master` branch of this repository to your GitHub profile. Do not fork the `gh-pages` branch as it only contains the "built" version.
+2. Create a branch to work on your changes
+3. Test your changes locally (see below for instructions on how to use Docusaurus)
+4. Create a Pull Request against the `master` branch to submit your changes
+
+
+## Install and Develop with Docusaurus
+
+This is not a tutorial on how to use Docusaurus. Please refer to Docusaurus documentation.
+
+### Installation
+
+On your local fork of the Documentation, use `yarn` to install
+the Docusaurus dependencies.
+
+```
+$ yarn
+```
+
+### Local Development
+
+Once the dependencies are installed, you can make changes to the documentation source files.
+
+Typically, only the files located under `/docs`, `/src` and `/blog` should be changed.
+
+Changes to the navigation and footer are made to the `docusauraus.config.js` file.
+
+To test locally your changes, run:
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live
+without having to restart the server.
+
+## Test builds
+
+A GitHub action is define to test builds. It will run on push to your fork.
+
+You may have to enable workflows on your fork before they are run.
+
+## Submit changes
+
+Once you are satisfied with your changes and the `Build GitHub Pages No Deploy` action has
+passed successfully, then create and submit a Pull Request against the `master` branch of
+the repository.
+

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/blog/2024-04-22-New-documentation.md

@@ -0,0 +1,9 @@
+---
+slug: new-documentation
+title: New documentation
+authors: [ericr]
+tags: [laminas, PHP, LmcAdmin, admin, LM-Commons]
+---
+This the new documentation site dedicated to the LmcAdmin module.
+
+There are no changes to the code, just improvements in the documentation.

docs/blog/authors.yml

@@ -0,0 +1,5 @@
+ericr:
+  name: Eric Richer
+  title: LM-Commons Administrator
+  url: https://github.com/visto9259
+  image_url: https://github.com/visto9259.png

docs/4.Authorization.md → docs/docs/Authorization.md

@@ -1,17 +1,12 @@
+---
+sidebar_position: 4
+---
 # Authorization
 LmcAdmin allows authorization via [LmcRbacMvc](https://github.com/LM-Commons/LmcRbacMvc). Configuration for LmcRbacMvc module is provided to easily configure LmcAdmin. Authorization enables you to restrict access to `/admin` and every other page under LmcAdmin.
 
 ## LmcRbacMvc authorization
 LmcRbacMvc works with `Laminas\Permission\Rbac` as access restriction component. The LmcRbacMvc module combines `Laminas\Permission\Rbac` with the standard user module [LmcUser](https://github.com/LM-Commons/LmcUser). To enable access restriction with LmcRbacMvc, install the module and enable it in your `application.config.php`.
 
-Furthermore, LmcAdmin has a `lmcadmin.global.php` file in the [config](../config/) directory. Copy this file over to your `config/autoload` directory. It directly provides LmcRbacMvc configuration to restrict access to users for the `/admin` route. Only users in the "admin" group are allowed to access LmcAdmin's pages.
+Furthermore, LmcAdmin has a `lmcadmin.global.php` file in the `/config` directory. Copy this file over to your `config/autoload` directory. It directly provides LmcRbacMvc configuration to restrict access to users for the `/admin` route. Only users in the "admin" group are allowed to access LmcAdmin's pages.
 
 Instructions for further configuration of LmcRbacMvc are provided in the [repository of LmcRbacMvc](https://github.com/LM-Commons/LmcRbacMvc).
-
-## Link to documentation pages
-
- 1. [Introduction](1.Introduction.md)
- 2. [Routes](2.Routes.md)
- 3. [Navigation](3.Navigation.md)
- 4. [Authorization](4.Authorization.md)
- 5. [Views & Layout](5.ViewLayout.md)

docs/1.Introduction.md → docs/docs/Introduction.md

@@ -1,10 +1,13 @@
+---
+sidebar_position: 1
+---
 # Introduction
 LmcAdmin is a low-level module that helps Laminas MVC Framework developers to create an admin interface. The module allows to have a uniform layout, navigation structure and routing scheme. You can create controllers routed as a child of LmcAdmin, so you can easily change the (root) url, access control and other properties. The navigation is also flexible, to allow you having a structure built of pages in the admin interface with menus, breadcrumbs and other links.
 
 Every part of LmcAdmin is customizable. In the pages listed below futher configuration options are explained. This documentation consists of the following pages:
 
- 1. [Introduction](1.Introduction.md)
- 2. [Routes](2.Routes.md)
- 3. [Navigation](3.Navigation.md)
- 4. [Authorization](4.Authorization.md)
- 5. [Views & Layout](5.ViewLayout.md)
+ 1. [Introduction](Introduction)
+ 2. [Routes](Routes)
+ 3. [Navigation](Navigation)
+ 4. [Authorization](Authorization)
+ 5. [Views & Layout](ViewLayout)

docs/3.Navigation.md → docs/docs/Navigation.md

@@ -1,11 +1,15 @@
+---
+sidebar_position: 3
+---
 # Navigation
 LmcAdmin allows a dedicated navigation structure for the admin interface. By default, LmcAdmin initiates a [Twitter Bootstrap](http://twitter.github.com/bootstrap) layout with on top the main admin navigation. These admin buttons are customizable.
 
 ## Add a page
-The admin structure requires at least a `label` for the navigation element and a `route` or `url` parameter for the link to be created. The `route` will use the `url()` view helper to construct a link. It is recommended to use [routes](2.Routes.md) in your child pages of LmcAdmin and therefore it is straightforward to use the `route` parameter in the navigation configuration.
+The admin structure requires at least a `label` for the navigation element and a `route` or `url` parameter for the link to be created. The `route` will use the `url()` view helper to construct a link. It is recommended to use [routes](Routes) in your child pages of LmcAdmin and therefore it is straightforward to use the `route` parameter in the navigation configuration.
 
 In the following example, there is a navigation element called "My Module" and points to `lmcadmin/foo/bar` as a route. This page is configured as follows:
 
+```php
     'navigation' => array(
         'admin' => array(
             'my-module' => array(
@@ -14,13 +18,6 @@ In the following example, there is a navigation element called "My Module" and p
             ),
         ),
     ),
+```
 
 The navigation in LmcAdmin uses `Laminas\Navigation` and more information about the configuration of this component is located in the [Laminas Mvc Framework](https://docs.laminas.dev/laminas-navigation/quick-start/) reference guide.
-
-## Link to documentation pages
-
- 1. [Introduction](1.Introduction.md)
- 2. [Routes](2.Routes.md)
- 3. [Navigation](3.Navigation.md)
- 4. [Authorization](4.Authorization.md)
- 5. [Views & Layout](5.ViewLayout.md)

docs/2.Routes.md → docs/docs/Routes.md

@@ -1,10 +1,13 @@
+---
+sidebar_position: 2
+---
 # Routes
 LmcAdmin enables a single route named `lmcadmin`, which is a literal route and standard using the url `/admin`. You can create child routes under `lmcadmin` so you enable urls like `/admin/foo` or `/admin/bar/baz`.
 
 ## Add child route
 To register a route as child route, the following example takes the option you name that route `foo`. The complete path should look like `/admin/foo`, so `foo` is a literal route with the route value `/foo`. Say you want this route to connect to your `MyModule\Controller\MyController` controller and the `index` action, create this config in your `module.config.php`:
 
-
+```php
     'router' => array(
         'routes' => array(
             'lmcadmin' => array(
@@ -23,10 +26,12 @@ To register a route as child route, the following example takes the option you n
             ),
         ),
     ),
+```
 
 ## Change the `/admin` url
 If you want your admin interface at `/backend` or something else, you must override the value of the route. In the following config, the `/admin` route value is replaced with `/backend`. Make sure this is enabled in a config where the module is registered *later* than LmcAdmin (otherwise, the config will not overwrite LmcAdmin's configuration):
 
+```php
     'router' => array(
         'routes' => array(
             'lmcadmin' => array(
@@ -35,10 +40,12 @@ If you want your admin interface at `/backend` or something else, you must overr
             ),
         ),
     ),
+```
 
 ## Change the controller behind `/admin`
 By default, the `/admin` url links to the `LmcAdmin\Controller\AdminController` controller. It's an empty action and a simple view script is rendered. If you want, for example, create a dashboard on the admin index page, you probably need to point the route to another controller. In the following config, the `lmcadmin` route's controller is replaced with `MyModule/Controller/AdminController` and the action is set to `dashboard`. Make sure this is enabled in a config where the module is registered *later* than LmcAdmin (otherwise, the config will not overwrite LmcAdmin's configuration):
 
+```php
     'router' => array(
         'routes' => array(
             'lmcadmin' => array(
@@ -51,11 +58,4 @@ By default, the `/admin` url links to the `LmcAdmin\Controller\AdminController`
             ),
         ),
     ),
-
-## Link to documentation pages
-
- 1. [Introduction](1.Introduction.md)
- 2. [Routes](2.Routes.md)
- 3. [Navigation](3.Navigation.md)
- 4. [Authorization](4.Authorization.md)
- 5. [Views & Layout](5.ViewLayout.md)
+```