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

[brandyscarney]

Start your review here 👉 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.

Doing so will require some formatting fixes (see Sass Guidelines) 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

[brandyscarney]

This file is necessary for generating GitHub pages from the markdown files

[brandyscarney]

I could remove this if we want since we aren't deploying GitHub pages yet but I want to make sure we don't forget about it needing to be here when we do

[sean-perkins]

Migration looks good, great work!

I don't have any blocking feedback. Docs content will be improved over time based on developer feedback and changes.

This is a big step in consolidating our information in one place, thank you!

[thetaPC]

Have we considered place the ToC on each page inside a expand?

[brandyscarney]

Have we considered place the ToC on each page inside a expand?

I don't want to mess with the existing content of the documentation too much, unless it's very obviously outdated/incorrect information. I mainly want to get all of the files in one place and then we can iterate on the content after that. I am playing around with a Jekyll theme that will showcase our documentation with a side bar and it has a specific way of defining the table of contents so we might need to edit it for that also: https://just-the-docs.github.io/just-the-docs/docs/navigation-structure/#in-page-navigation-with-table-of-contents

[thetaPC]

Just my comment about the links is left. I added my response.