Docs folder standardization and other fixes (#78)

luizcmarin · web-flow · commit 76342290b0f6 · 2024-04-22T23:41:16.000+03:00
diff --git a/LICENSE.md b/LICENSE.md
@@ -1,17 +1,17 @@
-Copyright © 2008 by Yii Software (https://www.yiiframework.com/)
+Copyright © 2008 by Yii Software (<https://www.yiiframework.com/>)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 
- * Redistributions of source code must retain the above copyright
+* Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
+* Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.
- * Neither the name of Yii Software nor the names of its
+* Neither the name of Yii Software nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.
 
diff --git a/README.md b/README.md
@@ -2,7 +2,6 @@
 
 This is a monorepo for Yii Development Panel and its SDK.
 
-
 ## Architecture
 
 The project follows monorepository patterns. The project consists of several packages:
@@ -21,7 +20,6 @@ The `toolbar` application. It is used to display the toolbar on the page.
 
 The package is used to display the toolbar on the page. It can be used separately from the `yii-dev-panel` application.
 
-
 The `toolbar` application requires only `sdk` package.
 
 ### `@yiisoft/yii-dev-toolbar`
@@ -38,9 +36,9 @@ The `app` application requires both `sdk` and `toolbar` packages.
 
 Example of remote components that may be used as a custom panel.
 
-Read more about how to work with remote components [here](docs/shared_components.md).
+Read more about how to work with remote components [here](docs/guide/readme.md).
 
-#### Dependency graph:
+#### Dependency graph
 
 ```mermaid
 flowchart LR
@@ -50,7 +48,31 @@ flowchart LR
     B[yii-dev-toolbar] --> C
 ```
 
-## Additional docs:
+## Documentation
+
+- [Guide](docs/guide/README.md)
+- [Internals](docs/internals.md)
+
+## Support
+
+If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
+You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
+
+## Support the project
+
+[![Open Collective](https://img.shields.io/badge/Open%20Collective-sponsor-7eadf1?logo=open%20collective&logoColor=7eadf1&labelColor=555555)](https://opencollective.com/yiisoft)
+
+## Follow updates
+
+[![Official website](https://img.shields.io/badge/Powered_by-Yii_Framework-green.svg?style=flat)](https://www.yiiframework.com/)
+[![Twitter](https://img.shields.io/badge/twitter-follow-1DA1F2?logo=twitter&logoColor=1DA1F2&labelColor=555555?style=flat)](https://twitter.com/yiiframework)
+[![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat&logo=telegram)](https://t.me/yii3en)
+[![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat&logo=facebook&logoColor=ffffff)](https://www.facebook.com/groups/yiitalk)
+[![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat&logo=slack)](https://yiiframework.com/go/slack)
+
+## License
+
+The Yii Development Panel is free software. It is released under the terms of the BSD License.
+Please see [`LICENSE`](./LICENSE.md) for more information.
 
-- [How to use Local registry (`verdaccio`)](docs/local_registry.md)
-- [How to work with remote components](docs/shared_components.md)
+Maintained by [Yii Software](https://www.yiiframework.com/).
diff --git a/docs/guide/README.md b/docs/guide/README.md
@@ -0,0 +1,5 @@
+# Yii Development Panel
+
+- [English](en/README.md)
+- [Português - Brasil](pt-BR/README.md)
+- [Internals](../internals.md)
diff --git a/docs/guide/en/README.md b/docs/guide/en/README.md
@@ -0,0 +1,4 @@
+# Yii Development Panel
+
+- [How to use Local registry (`verdaccio`)](local_registry.md)
+- [How to work with remote components](shared_components.md)
diff --git a/docs/guide/en/local_registry.md b/docs/guide/en/local_registry.md
@@ -11,11 +11,12 @@ To be able to use the local registry, you need:
 
 1. Run the local registry server
 
-```bash
+```shell
 npx verdaccio
 ```
 
 That will output:
+
 ```text
 info --- config file  - /Users/xepozz/.config/verdaccio/config.yaml
 info --- "crypt" algorithm is deprecated consider switch to "bcrypt". Read more: https://github.com/verdaccio/monorepo/pull/580
diff --git a/docs/guide/en/shared_components.md b/docs/guide/en/shared_components.md
diff --git a/docs/guide/pt-BR/README.md b/docs/guide/pt-BR/README.md
@@ -0,0 +1,4 @@
+# Yii Development Panel
+
+- [How to use Local registry (`verdaccio`)](local_registry.md)
+- [How to work with remote components](shared_components.md)
diff --git a/docs/guide/pt-BR/local_registry.md b/docs/guide/pt-BR/local_registry.md
@@ -0,0 +1,35 @@
+# How to use Local registry (`verdaccio`)
+
+## Purpose
+
+- Test the publishing process locally.
+- Test the installation process locally.
+
+## How to use
+
+To be able to use the local registry, you need:
+
+1. Run the local registry server
+
+```shell
+npx verdaccio
+```
+
+That will output:
+
+```text
+info --- config file  - /Users/xepozz/.config/verdaccio/config.yaml
+info --- "crypt" algorithm is deprecated consider switch to "bcrypt". Read more: https://github.com/verdaccio/monorepo/pull/580
+info --- plugin successfully loaded: verdaccio-htpasswd
+info --- plugin successfully loaded: verdaccio-audit
+warn --- http address - http://localhost:4873/ - verdaccio/5.23.2
+```
+
+2. Add the local registry to your `~/.npmrc` file:
+
+```text
+registry=http://localhost:4873/ <-- the url from the previous step
+```
+
+3. Run `npm adduser` and done this step.
+4. Run `npm publish` in the root of the package you want to publish or use `npm publish -ws` to publish all packages in the monorepo.
diff --git a/docs/guide/pt-BR/shared_components.md b/docs/guide/pt-BR/shared_components.md
@@ -0,0 +1,35 @@
+# How to work with remote components
+
+## About
+
+Remote components are components that are located in a remote repository. 
+They are not installed in the project, but are used as if they were provided from the backend. 
+This feature allows you to create custom panels for the `yii-dev-panel` and render them as native components.
+
+### How to test
+
+First of all, you need to serve the `yii-dev-panel`.
+
+Open a terminal and run:
+```sh
+cd packages/yii-dev-panel; npm start
+```
+It serves the yii-dev-panel project on `127.0.0.1:3000`. 
+
+Then you need to serve your own built remote components. As an example you may use `examples/remote-panel` project.
+Open a new terminal and run:
+```sh
+cd examples/remote-panel; npm run serve:dev
+```
+It serves an example project on `127.0.0.1:3002`.
+
+Then open the file `packages/yii-dev-panel-sdk/src/Pages/Layout.tsx` and apply the following changes:
+```diff
+    {name: 'Open API', link: '/open-api'},
+    // Uncomment to debug shared components
+-    // {name: 'Shared', link: '/shared'},
++    {name: 'Shared', link: '/shared'},
+```
+
+Now you can open `http://localhost:3000/shared` and see the remote component in action.
+
diff --git a/docs/internals.md b/docs/internals.md
@@ -0,0 +1,45 @@
+# Internals
+
+## Unit testing
+
+The package is tested with [PHPUnit](https://phpunit.de/). To run tests:
+
+```shell
+./vendor/bin/phpunit
+```
+
+## Mutation testing
+
+The package tests are checked with [Infection](https://infection.github.io/) mutation framework with
+[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it:
+
+```shell
+./vendor/bin/roave-infection-static-analysis-plugin
+```
+
+## Static analysis
+
+The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis:
+
+```shell
+./vendor/bin/psalm
+```
+
+## Rector
+
+Use [Rector](https://github.com/rectorphp/rector) to make codebase follow some specific rules or
+use either newest or any specific version of PHP:
+
+```shell
+./vendor/bin/rector
+```
+
+## Composer require checker
+
+This package uses [composer-require-checker](https://github.com/maglnet/ComposerRequireChecker) to check if all dependencies are correctly defined in `composer.json`.
+
+To run the checker, execute the following command:
+
+```shell
+./vendor/bin/composer-require-checker
+```
diff --git a/examples/remote-panel/README.md b/examples/remote-panel/README.md
@@ -6,23 +6,23 @@ It is a simple example of how to use the remote panel.
 
 1. Run the server
 
-```bash
+```shell
 npm start
 ```
 
 2. Open the browser and go to `http://localhost:3002`
 
 > Port is 3002 because the yii-dev-panel is running on port 3000
-> 
+>
 > You can change the port in the `package.json` file
 
 3. You may use the remote panel to debug your application in the browser.
 4. When you are done, you need to build the application to prepare the production files.
 
-```bash
+```shell
 npm run build
 ```
 
 5. All is you need is to add the `dist` folder your application assets to be served by the web server.
 
-6. More about the remote panel on the backend, please visit [yii-debug]
+6. More about the remote panel on the backend, please visit [yii-debug]
diff --git a/packages/yii-dev-panel-sdk/LICENSE.md b/packages/yii-dev-panel-sdk/LICENSE.md
@@ -1,17 +1,17 @@
-Copyright © 2008 by Yii Software (https://www.yiiframework.com/)
+Copyright © 2008 by Yii Software (<https://www.yiiframework.com/>)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 
- * Redistributions of source code must retain the above copyright
+* Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
+* Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.
- * Neither the name of Yii Software nor the names of its
+* Neither the name of Yii Software nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.
 
diff --git a/packages/yii-dev-panel/LICENSE.md b/packages/yii-dev-panel/LICENSE.md
@@ -1,17 +1,17 @@
-Copyright © 2008 by Yii Software (https://www.yiiframework.com/)
+Copyright © 2008 by Yii Software (<https://www.yiiframework.com/>)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 
- * Redistributions of source code must retain the above copyright
+* Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
+* Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.
- * Neither the name of Yii Software nor the names of its
+* Neither the name of Yii Software nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.
 
diff --git a/packages/yii-dev-toolbar/LICENSE.md b/packages/yii-dev-toolbar/LICENSE.md
@@ -1,17 +1,17 @@
-Copyright © 2008 by Yii Software (https://www.yiiframework.com/)
+Copyright © 2008 by Yii Software (<https://www.yiiframework.com/>)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 
- * Redistributions of source code must retain the above copyright
+* Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
+* Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.
- * Neither the name of Yii Software nor the names of its
+* Neither the name of Yii Software nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.
 
diff --git a/packages/yii-dev-toolbar/README.md b/packages/yii-dev-toolbar/README.md
@@ -14,6 +14,7 @@ npm i @yiisoft/yii-dev-toolbar
 
 First you need to tell `npm` to use GitHub Packages registry for @yiisoft scope.
 Add `@yiisoft:registry=https://npm.pkg.github.com` to `.npmrc` file or run the following command:
+
 ```shell
 echo "\n@yiisoft:registry=https://npm.pkg.github.com" >> .npmrc
 ```
@@ -33,4 +34,3 @@ Add the following code to the page to display the toolbar:
 <script src="https://yiisoft.github.io/yii-dev-panel/toolbar/bundle.js"></script>
 <link rel="stylesheet" href="https://yiisoft.github.io/yii-dev-panel/toolbar/bundle.css" />
 ```
-
