chore(docs): consolidate the developer resource files into a docs/ directory (#29266)

Start your review here 👉
[docs/README.md](https://github.com/ionic-team/ionic-framework/blob/FW-6107/docs/README.md)

## What is the current behavior?

Documentation files with information on how to contribute, component
implementations, testing, etc. are scattered throughout various folders
in this repository.

## What is the new behavior?

Consolidates the documentation files into a root `docs/` directory for
easier discovery and organization.

`/docs` tree:

```
├── _config.yml
├── component-guide.md
├── CONTRIBUTING.md
├── README.md
├── sass-guidelines.md
├── angular
│   ├── README.md
│   └── testing.md
├── core
│   ├── README.md
│   └── testing
│       ├── README.md
│       ├── api.md
│       ├── best-practices.md
│       ├── preview-changes.md
│       └── usage-instructions.md
├── react
│   ├── README.md
│   └── testing.md
├── react-router
│   ├── README.md
│   └── testing.md
├── vue
│   ├── README.md
│   └── testing.md
└── vue-router
    ├── README.md
    └── testing.md
```

**Migrates the following:**

| Previous Location | New Location |
| ----------------------------------------------------------- |
----------------------------------------- |
| `.github/COMPONENT-GUIDE.md` | `docs/component-guide.md` |
| `.github/CONTRIBUTING.md` | `docs/CONTRIBUTING.md` |
| `core/scripts/README.md` | `docs/core/testing/preview-changes.md` |
| `core/src/utils/test/playwright/docs/api.md` |
`docs/core/testing/api.md` |
| `core/src/utils/test/playwright/docs/best-practices.md` |
`docs/core/testing/best-practices.md` |
| `core/src/utils/test/playwright/docs/README.md` |
`docs/core/testing/README.md` |
| `core/src/utils/test/playwright/docs/usage-instructions.md` |
`docs/core/testing/usage-instructions.md` |
| `packages/angular/test/README.md` | `docs/angular/testing.md` |
| `packages/react-router/test/README.md` |
`docs/react-router/testing.md` |
| `packages/react/test/README.md` | `docs/react/testing.md` |
| `packages/react/test/base/README.md` | `docs/react/testing.md` |
| `packages/vue/test/README.md` | `docs/vue/testing.md` |

**Adds the following:**

| File | Description |
| ----------------------------- |
-----------------------------------------------------------------------
|
| `docs/sass-guidelines.md` | Sass Variable guidelines taken from
`ionic-framework-design-documents` |
| `docs/README.md` | Entry file that should link to all other files |
| `docs/_config.yml` | Config file for use with GitHub pages |
| `docs/core/README.md` | Description of core, links to contributing and
testing |
| `docs/angular/README.md` | Description of angular, links to
contributing and testing |
| `docs/react/README.md` | Description of react, links to contributing
and testing |
| `docs/react-router/README.md` | Description of react-router, links to
contributing and testing |
| `docs/vue/README.md` | Description of vue, links to contributing and
testing |
| `docs/vue-router/README.md` | Description of vue-router, links to
contributing and testing |
| `docs/vue-router/testing.md` | Testing file for vue-router, populated
from vue-router's main README |

**Does not** add any files for `angular-server`. This is because the
README is essentially empty and there is no testing in that directory. I
can add blank files if we want to have something to add to later.

**Does not** migrate the content of the packages' root `README.md`
files. These files are used for their npm package descriptions so we
should not edit them.

## Hosting Documentation

We can (and should) host these files using GitHub Pages. I have
duplicated them in a personal repository to see how this would look:
[docs-consolidation](https://brandyscarney.github.io/docs-consolidation/).

Doing so will require some formatting fixes (see [Sass
Guidelines](https://brandyscarney.github.io/docs-consolidation/sass-guidelines.html#-reusable-values))
so I did not publish them now but we can easily enable GitHub pages by
toggling a setting in this repository.

## Other information

- Verify that no documentation files were missed in the migration
- You can use these commands to search for `*.md` files in a directory:
    - `find core/src -type f -name "*.md" -print`
- `find packages/angular -type f -name "*.md" -not -path
"**/node_modules/*" -print`
- I did add some redirect links in some of the existing markdown files
so they might still exist for that reason
- We should probably break up the contributing + component guide
documentation into smaller files, such as including best practices, but
I wanted to get everything in the same place first
- The contributing has sections on each of the packages that we could
move to that package's docs folder:
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#core

---------

Co-authored-by: Maria Hutt <thetaPC@users.noreply.github.com>
This commit is contained in:
Brandy Carney
2024-04-08 15:06:26 -04:00
committed by GitHub
parent 7b6c330f17
commit b315b0cb29
32 changed files with 1140 additions and 382 deletions

View File

@ -1,47 +1,3 @@
# React Test App
## Getting Started
### Setup
Make sure you are using the latest versions of node and npm. If you do not have these, [download the installer](https://nodejs.org/) for the LTS version of Node.js. This is the best way to also [install npm](https://blog.npmjs.org/post/85484771375/how-to-install-npm#_=_).
### Building Dependencies
Navigate to the `core`, `packages/react` and `packages/react-router` directories and build each of them:
```bash
npm i
npm run build
```
Then, install dependencies from this directory for this test app:
```
npm i
```
### Syncing Changes
When making changes to the React package, run the following from this directory to sync the changes:
```bash
npm run sync
```
### Previewing App
To preview this app locally, run the following from this directory:
```bash
npm start
```
### Running Tests
To run the e2e tests, run the following from this directory:
```
npm run build
npm run e2e
```
Refer to the [React Testing documentation](/docs/react/testing.md) in order to build and run the test app.