feat: adding documentation with vitepress (#80)

.gitignore

@@ -71,6 +71,7 @@ versions.json
 
 # Dist
 /dist
+/docs/.vitepress/dist
 
 # Faker
 TAGS

CONTRIBUTING.md

@@ -1,15 +1,13 @@
-A lot of effort has been put into `faker.js` to create a useful and handy
-library. There are still a lot of things to be done, so all contributions are
-welcome! If you can make `faker.js` better, please read the following contribution guide.
+A lot of effort has been put into `Faker` to create a useful and handy
+library. There are still a lot of things to be done, so all contributions are welcome! If you can make `Faker` better, please read the following contribution guide.
 
 # Important
 
 - Please make sure that you run both `gulp` and tests before making a PR.
 
 ## Support
 
-`faker.js` relies on [commonJS](http://www.commonjs.org/) standard and supports both node.js and the
-browsers. Keep this in mind, when modifying and/or extending the sources.
+`Faker` relies on [commonJS](http://www.commonjs.org/) standard and supports both node.js and the browsers. Keep this in mind, when modifying and/or extending the sources.
 
 ## Automation
 

README.md

@@ -1,6 +1,6 @@
 # Faker
 
-Generate massive amounts of fake data in the browser and node.js.
+Generate massive amounts of fake data in the Browser and Node.js.
 
 [![Chat on Discord](https://img.shields.io/discord/929487054990110771)](https://discord.com/invite/4qDjAmDj4P)
 [![Continuous Integration](https://github.com/faker-js/faker/actions/workflows/ci.yml/badge.svg)](https://github.com/faker-js/faker/actions/workflows/ci.yml)
@@ -29,7 +29,7 @@ declare module '@faker-js/faker' {
 
 This project was originally created and hosted at https://github.com/marak/Faker.js/ - however around 4th Jan, 2022 - the author decided to delete the repository (for unknown reasons).
 
-In the interest of the community, it has been decided that faker.js will continue to be maintained here and all help in its development will be appreciated.
+In the interest of the community, it has been decided that Faker will continue to be maintained here and all help in its development will be appreciated.
 
 ## Demo
 
@@ -290,7 +290,7 @@ var randomCard = faker.helpers.createCard(); // random contact card containing m
 
 ### Faker.fake()
 
-faker.js contains a super useful generator method `Faker.fake` for combining faker API methods using a mustache string format.
+Faker contains a super useful generator method `Faker.fake` for combining faker API methods using a mustache string format.
 
 **Example:**
 
@@ -304,7 +304,7 @@ This will interpolate the format string with the value of methods `name.lastName
 
 ## Localization
 
-As of version `v2.0.0` faker.js has support for multiple localities.
+As of version `v2.0.0` Faker has support for multiple localities.
 
 The default language locale is set to English.
 
@@ -364,7 +364,7 @@ faker.locale = 'de';
 
 ### Individual Localization Packages
 
-faker.js supports incremental loading of locales.
+Faker supports incremental loading of locales.
 
 By default, requiring `faker` will include _all_ locale data.
 
@@ -392,6 +392,35 @@ var secondRandom = faker.datatype.number();
 console.log(firstRandom === secondRandom);
 ```
 
+## Documentation
+
+Faker is currently in the process of migrating its documentation to Vitepress (the successor of Vuepress).
+
+**Developing the docs**
+
+```shell
+# build the Faker library for the browser
+# it's used inside of certain routes
+npm run browser
+
+npm run docs:dev
+```
+
+**Building and serving the docs statically**
+
+```shell
+# build the Faker library for the browser
+# it's used inside of certain routes
+npm run browser
+
+npm run docs:build # Output docs to /dist
+npm run docs:serve # Serve docs from /dist
+```
+
+## Deploying Documentation
+
+The website is kindly hosted for free by the Netlify team under their Open Source plan. See the netlify.toml for configuration.
+
 ## Tests
 
 ```shell
@@ -401,9 +430,9 @@ npm run test
 
 You can view a code coverage report generated in coverage/lcov-report/index.html.
 
-## Building faker.js
+## Building Faker
 
-faker uses [gulp](http://gulpjs.com/) to automate its build process. Each build operation is a separate task which can be run independently.
+Faker uses [gulp](http://gulpjs.com/) to automate its build process. Each build operation is a separate task which can be run independently.
 
 ### Browser Bundle
 

docs/.vitepress/config.mjs

@@ -0,0 +1,114 @@
+import { defineConfig } from 'vitepress';
+
+const nav = [
+  { text: 'Guide', link: '/guide/' },
+  // { text: 'Playground', link: '/playground/' },
+];
+
+const sidebar = {
+  '/': [
+    {
+      text: 'Guide',
+      children: [
+        {
+          text: 'Recent Statement and FAQs',
+          link: '/guide/recent-faqs',
+        },
+        {
+          text: 'Getting Started',
+          link: '/guide/',
+        },
+      ],
+    },
+    {
+      text: 'API',
+      children: [
+        {
+          text: 'Address',
+          link: '/api/address',
+          collapsable: false, // optional, defaults to true
+        },
+        {
+          text: 'Commerce',
+          link: '/api/commerce',
+        },
+        {
+          text: 'Company',
+          link: '/api/company',
+        },
+        {
+          text: 'Database',
+          link: '/api/database',
+        },
+        {
+          text: 'Datatype',
+          link: '/api/datatype',
+        },
+        {
+          text: 'Date',
+          link: '/api/date',
+        },
+        {
+          text: 'Fake',
+          link: '/api/fake',
+        },
+        {
+          text: 'Finance',
+          link: '/api/finance',
+        },
+        {
+          text: 'Hacker',
+          link: '/api/hacker',
+        },
+        {
+          text: 'Helpers',
+          link: '/api/helpers',
+        },
+        {
+          text: 'Image',
+          link: '/api/image',
+        },
+        {
+          text: 'Internet',
+          link: '/api/internet',
+        },
+        {
+          text: 'Localization',
+          link: '/api/localization',
+        },
+      ],
+    },
+  ],
+};
+
+// grab from process.env once this is building on netlify
+const algolia = {
+  apiKey: '',
+  indexName: '',
+  searchParameters: {
+    facetFilters: [''],
+  },
+};
+
+export default defineConfig({
+  // Empty in order to use the faker.js logo instead of a text title.
+  // If we had a square logo, we could use it here.
+  title: 'Faker',
+  description:
+    'Generate massive amounts of fake data in the browser and node.js',
+  head: [
+    ['link', { rel: 'icon', href: '/logo.svg' }],
+    ['meta', { name: 'theme-color', content: '#40af7c' }],
+  ],
+  themeConfig: {
+    repo: 'faker-js/faker',
+    logo: '/logo.svg',
+    docsDir: 'docs',
+    docsBranch: 'main',
+    editLinks: true,
+    editLinkText: 'Suggest changes to this page',
+    nav,
+    sidebar,
+    algolia,
+  },
+});

docs/.vitepress/theme/components/Badge.vue

@@ -0,0 +1,43 @@
+<script setup>
+defineProps({
+  text: String,
+  type: String,
+  vertical: String,
+});
+</script>
+
+<template>
+  <span class="badge" :class="type" :style="{ verticalAlign: vertical }">
+    {{ text }}
+  </span>
+</template>
+
+<style scoped>
+.badge.tip {
+  background-color: #40af7c;
+}
+
+.badge.danger {
+  background-color: #cb0300;
+}
+
+.badge.warning {
+  background-color: #e7c000;
+}
+
+.badge.info {
+  background-color: #476482;
+}
+
+.badge {
+  display: inline-block;
+  font-size: 14px;
+  height: 18px;
+  line-height: 18px;
+  border-radius: 3px;
+  padding: 0 6px;
+  color: var(--c-bg);
+  vertical-align: top;
+  transition: color var(--t-color), background-color var(--t-color);
+}
+</style>

docs/.vitepress/theme/components/Playground.vue

@@ -0,0 +1,18 @@
+<script setup>
+import { ref } from 'vue';
+
+const faker = ref();
+const ready = ref(false);
+
+import('../../../../dist/faker').then((_faker) => {
+  window.faker = _faker.default;
+  faker.value = _faker.default;
+  ready.value = true;
+});
+</script>
+
+<template>
+  <h2>🚧 Playground under construction 🚧</h2>
+  <h3>window.faker</h3>
+  <pre v-if="ready">{{ Object.keys(faker) }}</pre>
+</template>

docs/.vitepress/theme/components/index.mjs

@@ -0,0 +1,7 @@
+import Playground from './Playground.vue';
+import Badge from './Badge.vue';
+
+export default {
+  Playground,
+  Badge,
+};

docs/.vitepress/theme/index.mjs

@@ -0,0 +1,11 @@
+import GlobalComponents from './components';
+import DefaultTheme from 'vitepress/theme';
+
+export default {
+  ...DefaultTheme,
+  enhanceApp({ app }) {
+    for (const [name, component] of Object.entries(GlobalComponents)) {
+      app.component(name, component);
+    }
+  },
+};