Merge pull request #515 from no-chris/add-documentation-site

Add documentation site
no-chris · Dec 20, 2021 · 5f1aade · 5f1aade
2 parents bf08fc8 + 0f0ba91
commit 5f1aade
Show file tree

Hide file tree

Showing 64 changed files with 9,156 additions and 24 deletions.
diff --git a/.prettierignore b/.prettierignore
@@ -2,4 +2,5 @@ coverage
 node_modules
 build
 SLOC
-package.json
+package.json
+.docusaurus
diff --git a/package.json b/package.json
@@ -55,7 +55,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/no-chris/chords-charts-studio.git"
+    "url": "git+https://github.com/no-chris/.chord-charts-studio.git"
   },
   "bugs": {
     "url": "https://github.com/no-chris/chords-charts-studio/issues"

diff --git a/packages/chord-charts-studio/SLOC b/packages/chord-charts-studio/SLOC
@@ -2,8 +2,8 @@ Source code:
 
 ---------- Result ------------
 
-            Physical :  6331
-              Source :  5237
+            Physical :  6330
+              Source :  5236
              Comment :  128
  Single-line comment :  60
        Block comment :  68
@@ -38,8 +38,8 @@ Total:
 
 ---------- Result ------------
 
-            Physical :  13734
-              Source :  11339
+            Physical :  13733
+              Source :  11338
              Comment :  193
  Single-line comment :  118
        Block comment :  75

diff --git a/packages/chord-charts-studio/assets/favicon.ico b/packages/chord-charts-studio/assets/favicon.ico
diff --git a/...o/build/css/main.07295dfda419c9b7ab93.css → ...o/build/css/main.8021d68be529720cfa48.css b/...o/build/css/main.07295dfda419c9b7ab93.css → ...o/build/css/main.8021d68be529720cfa48.css
diff --git a/...ild/css/main.07295dfda419c9b7ab93.css.map → ...ild/css/main.8021d68be529720cfa48.css.map b/...ild/css/main.07295dfda419c9b7ab93.css.map → ...ild/css/main.8021d68be529720cfa48.css.map
diff --git a/packages/chord-charts-studio/build/favicon.ico b/packages/chord-charts-studio/build/favicon.ico
diff --git a/packages/chord-charts-studio/build/index.html b/packages/chord-charts-studio/build/index.html
@@ -2,4 +2,4 @@
         function gtag(){dataLayer.push(arguments);}
         gtag('js', new Date());
 
-        gtag('config', 'G-EGKBT2J600');</script><link rel="icon" href="favicon.ico"><script defer="defer" src="vendors.07295dfda419c9b7ab93.js"></script><script defer="defer" src="main.07295dfda419c9b7ab93.js"></script><link href="css/main.07295dfda419c9b7ab93.css" rel="stylesheet"></head><body><div id="app" class="theme-dark"></div></body></html>
+        gtag('config', 'G-EGKBT2J600');</script><link rel="icon" href="app/favicon.ico"><script defer="defer" src="app/vendors.8021d68be529720cfa48.js"></script><script defer="defer" src="app/main.8021d68be529720cfa48.js"></script><link href="app/css/main.8021d68be529720cfa48.css" rel="stylesheet"></head><body><div id="app" class="theme-dark"></div></body></html>
diff --git a/packages/chord-charts-studio/build/main.07295dfda419c9b7ab93.js b/packages/chord-charts-studio/build/main.07295dfda419c9b7ab93.js
diff --git a/packages/chord-charts-studio/build/main.07295dfda419c9b7ab93.js.map b/packages/chord-charts-studio/build/main.07295dfda419c9b7ab93.js.map
diff --git a/packages/chord-charts-studio/build/main.8021d68be529720cfa48.js b/packages/chord-charts-studio/build/main.8021d68be529720cfa48.js
diff --git a/packages/chord-charts-studio/build/main.8021d68be529720cfa48.js.map b/packages/chord-charts-studio/build/main.8021d68be529720cfa48.js.map
diff --git a/...dio/build/vendors.07295dfda419c9b7ab93.js → ...dio/build/vendors.8021d68be529720cfa48.js b/...dio/build/vendors.07295dfda419c9b7ab93.js → ...dio/build/vendors.8021d68be529720cfa48.js
diff --git a/...ndors.07295dfda419c9b7ab93.js.LICENSE.txt → ...ndors.8021d68be529720cfa48.js.LICENSE.txt b/...ndors.07295dfda419c9b7ab93.js.LICENSE.txt → ...ndors.8021d68be529720cfa48.js.LICENSE.txt
diff --git a/...build/vendors.07295dfda419c9b7ab93.js.map → ...build/vendors.8021d68be529720cfa48.js.map b/...build/vendors.07295dfda419c9b7ab93.js.map → ...build/vendors.8021d68be529720cfa48.js.map
diff --git a/packages/chord-charts-studio/package.json b/packages/chord-charts-studio/package.json
@@ -10,7 +10,7 @@
 	},
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/no-chris/chords-charts-studio.git"
+		"url": "git+https://github.com/no-chris/.chord-charts-studio.git"
 	},
 	"bugs": {
 		"url": "https://github.com/no-chris/chords-charts-studio/issues"

diff --git a/packages/chord-charts-studio/src/ui/sideBar/_components/UserGuide.js b/packages/chord-charts-studio/src/ui/sideBar/_components/UserGuide.js
@@ -5,8 +5,7 @@ import React from 'react';
 import Button from '../../_components/Button';
 import Icon from '../../_components/Icon.js';
 
-const userGuideUrl =
-	'https://chordmark.netlify.app/docs/chord-charts-studio/overview';
+const userGuideUrl = 'https://chord-charts-studio.netlify.app';
 
 const UserGuide = () => {
 	const openUserGuide = () => {

diff --git a/packages/chord-charts-studio/webpack.common.js b/packages/chord-charts-studio/webpack.common.js
@@ -1,7 +1,6 @@
 /* eslint-env node */
 const path = require('path');
 
-const HtmlWebpackPlugin = require('html-webpack-plugin');
 const MiniCssExtractPlugin = require('mini-css-extract-plugin');
 
 const buildDir = 'build';
@@ -19,11 +18,6 @@ const config = {
 	},
 
 	plugins: [
-		new HtmlWebpackPlugin({
-			title: 'Chord Charts Studio',
-			template: 'assets/index.html',
-			favicon: 'assets/favicon.ico',
-		}),
 		new MiniCssExtractPlugin({
 			filename: 'css/[name].[fullhash].css',
 		}),

diff --git a/packages/chord-charts-studio/webpack.dev.js b/packages/chord-charts-studio/webpack.dev.js
@@ -2,17 +2,27 @@
 const { merge } = require('webpack-merge');
 const common = require('./webpack.common');
 const path = require('path');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
 
 module.exports = merge(common, {
 	mode: 'development',
 
 	devtool: 'inline-source-map',
 
+	plugins: [
+		new HtmlWebpackPlugin({
+			title: 'Chord Charts Studio',
+			template: 'assets/index.html',
+			favicon: 'assets/favicon.ico',
+		}),
+	],
+
 	devServer: {
 		hot: true,
 		static: {
 			directory: path.join(__dirname, 'assets'),
 			watch: true,
+			publicPath: '/app',
 		},
 		historyApiFallback: true,
 		port: 8084, // config.devServer.port,

diff --git a/packages/chord-charts-studio/webpack.prod.js b/packages/chord-charts-studio/webpack.prod.js
@@ -7,6 +7,7 @@ const common = require('./webpack.common');
 const TerserPlugin = require('terser-webpack-plugin');
 const { CleanWebpackPlugin } = require('clean-webpack-plugin');
 const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
 const BundleAnalyzerPlugin =
 	require('webpack-bundle-analyzer').BundleAnalyzerPlugin;
 
@@ -40,5 +41,11 @@ module.exports = merge(common, {
 			analyzerMode: 'static',
 			openAnalyzer: false,
 		}),
+		new HtmlWebpackPlugin({
+			title: 'Chord Charts Studio',
+			template: 'assets/index.html',
+			favicon: 'assets/favicon.ico',
+			publicPath: 'app', // subfolder of the documentation website
+		}),
 	],
 });
diff --git a/packages/documentation/.eslintrc.js b/packages/documentation/.eslintrc.js
@@ -0,0 +1,12 @@
+/* eslint-env node */
+module.exports = {
+	extends: ['eslint:recommended', 'plugin:react/recommended'],
+	rules: {
+		'react/prop-types': 0,
+	},
+	settings: {
+		react: {
+			version: 'detect',
+		},
+	},
+};
diff --git a/packages/documentation/.gitignore b/packages/documentation/.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*
diff --git a/packages/documentation/README.md b/packages/documentation/README.md
@@ -0,0 +1,33 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ 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.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+```
+$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
diff --git a/packages/documentation/babel.config.js b/packages/documentation/babel.config.js
@@ -0,0 +1,4 @@
+/* eslint-env node */
+module.exports = {
+	presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/packages/documentation/docs/assets/ccs1.png b/packages/documentation/docs/assets/ccs1.png
diff --git a/packages/documentation/docs/assets/ccs2.png b/packages/documentation/docs/assets/ccs2.png
diff --git a/packages/documentation/docs/faq.mdx b/packages/documentation/docs/faq.mdx
@@ -0,0 +1,28 @@
+import { CM, CCS, CS } from '../src/components/shortcuts';
+
+# FAQ
+
+## Where are my songs stored?
+
+<CCS/> use the browser's memory (local storage) to store the songs. 
+This has a huge advantage: since I don't need to pay for a server to store the user content, you can enjoy <CCS/> for free.
+Of course, there are some drawbacks as well: if you switch computers, devices, or browsers, you will start with a blank library every time.
+
+## Can I backup the songs library?
+
+Not easily for now, but you can export each individual song.
+Tech-savvy users can also directly access the local storage content and back it up, for example, in [Chrome](https://developer.chrome.com/docs/devtools/storage/localstorage/).
+
+## Can I see the sample content again? 
+
+When you start <CCS/> for the first time, it comes with two samples of "songs."
+If you deleted them and would like to see them again, you can either:
+
+- delete all the songs in the library and refresh the browser
+- open <CCS/> in an incognito session or in another browser
+
+## The layout is broken when printing
+
+If the browser's printing preview looks different than <CCS/>'s preview, make sure:
+- to set the document size as `A4`
+- to disable the printer's margins, since they are directly handled by <CCS/>
diff --git a/packages/documentation/docs/import.mdx b/packages/documentation/docs/import.mdx
@@ -0,0 +1,53 @@
+import { CM, CCS, CS } from '../src/components/shortcuts';
+import TabbedChordMark from '../src/components/TabbedChordMark';
+
+# Importing songs
+
+## The import dialog
+
+Hitting the **Import** button will bring the following dialog:
+
+![Chord Charts Studio](./assets/ccs2.png)
+
+Importing songs can be done:
+
+- by copy/pasting content in the input box on the left side (typically a chord chart that you will find on another website)
+- by selecting a file on your hard drive, for example, a ChordPro file 
+
+The right side of the import dialog will show a preview of the input converted in the <CM/> format.
+If the conversion doesn't look right, you can adjust the input format:
+
+- **Basic**: should work for most chord charts where the chord symbols are positioned over the lyrics, which is the standard way of rendering chord charts in most websites
+- **ChordPro**: use this setting if the input source is in the [ChordPro](https://www.chordpro.org/) format, eg, with chords encoded between square brackets directly in the lyrics
+- **Ultimate Guitar**: very similar to **Basic**, but also recognize some of the specific syntax used by chord charts on the [Ultimate Guitar](https://www.ultimate-guitar.com/) website.
+
+Of course, recognizing if the conversion "looks right" or not requires a bit of practice with the <CM/> format.
+
+Once you are happy with the settings, hit the **IMPORT** button in the top right corner. 
+
+## Encoding rhythm information
+
+Since <CM/> is the only chord chart format that encodes rhythm information, you will need to add this information manually to each chord symbol after importing a song.
+There are three possibilities, depending on the duration of a chord:
+
+### Exactly one bar
+
+Lucky you! There is nothing specific to do here, since by default, <CM/> will interpret a chord symbol as lasting a full bar. 
+
+<TabbedChordMark src={'A E\n_By default, all chords _lasts a full bar'} />
+
+### Less than one bar
+
+Use the chord duration marker `.` to specify how many beats the chord should be played.
+You might also need to specify the song time signature if different than 4/4.
+
+<TabbedChordMark src={'5/4\nA... D. E.\n_Three chords in a _single 5/4 _bar'} />
+
+### More than one bar
+
+A bit of extra work is needed here. 
+You need to repeat the chord as many times as it should be played for the duration of a full bar.
+Use the bar repeat symbol `%` to make that process quicker. 
+For a better result, chord position markers should also be repeated in the lyric line.
+
+<TabbedChordMark src={'A %%\n_The same chord _over multiple bars _need to be repeated'} />
diff --git a/packages/documentation/docs/interface.mdx b/packages/documentation/docs/interface.mdx
@@ -0,0 +1,98 @@
+import { CM, CCS, CS } from '../src/components/shortcuts';
+
+# User interface
+
+![Chord Charts Studio](./assets/ccs1.png)
+
+The primary user interface is made of four parts:
+
+- the "song manager" on the left
+- the "Mode switcher" at the top
+- the main area
+- the options panel on the right
+
+## The Song manager
+
+The song manager offers the following functionality:
+
+- **Import**: creates a new song from an external source/format, typically from a file or another website, and convert it to <CM />. See the [import documentation](/docs/import).
+- **New**: creates a new song from scratch in the <CM/> format
+- **Rename**: allows renaming the currently selected song. You can also double-click on the song title directly.
+- **Delete**: allows deleting the currently selected song (needs confirmation)
+- **Print**: switches to the **Print/PDF Preview** mode and display the browser printing dialog
+- **Export**: switches to the **Export Preview** mode and display the browser file saving dialog
+
+To switch from one song to another, click on a title in the song list below the actions buttons.
+
+## Main area & the mode switcher
+
+When a song is selected, it will be displayed in the main area and adapt to the selected mode:
+
+- **Edit**: this is where the actual writing of the chord chart takes place. 
+You write on the left pane, and the right pane will show you in real-time the final output.
+Of course, the chord chart needs to follow [the ChordMark syntax](https://chordmark.netlify.app).
+- **Screen view**: this mode is helpful if you wish to play the song by directly looking at your computer screen.
+You can format the chord chart such as it nicely fits the screen real estate, and you don't need to scroll when playing (for example, using multiple columns).
+To further increase the screen real estate, you can fold both the right and left sidebars.
+- **Print/PDF Preview**: this mode shows you a preview of how the song will look when printed on an A4 paper or exported as a PDF. 
+Here again, you can tweak the settings such as the song fits on a single sheet of paper (or as many as you want): number of columns, font size, etc.
+- **Export Preview**: finally, this mode allows you to prepare the chord chart for being exported as a text file. A ChordPro export is available.
+
+It is important to stress that all formatting options are not available in all modes: 
+for example, text documents do not support columns, so the columns setting is not available in the **Export Preview** mode.
+
+Equally important, when an option is available in more than one mode, then it is saved for the current mode only, independently of the others. 
+In other words, you can have a setting of 4 columns for the screen view and two columns for the printed one, for example.
+The "Key" settings, however, are set once for all the modes.
+
+## The options panel
+
+The song display can be customized with the following options:
+
+### Editor preferences
+
+These options apply to all Chord Charts.
+
+- **Theme**: Theme for ChordMark rendering, both in Editor preview and in the screen view
+- **Export format**: 
+    - **ChordMark**: format the song using the <CM/> rendering
+    - **ChordMark (Source)**: use this setting to export the song in the source <CM/> format
+    - **ChordPro**: convert the song in the ChordPro format (beta)
+
+
+### Key
+
+These options apply to all rendering modes of a single Chord Chart.
+
+- **Transpose**: use this slider to transpose up or down the chords
+- **Harmonize accidentals**: enable this option if you want all chords symbols to be rendered with the same accidentals
+- **Preferred accidentals**: only available if the previous option is turned on
+    - **Auto**: the accidental with the most occurrences in the song will be used 
+    - **#**: render all accidentals with sharps
+    - **b**: render all accidentals with flats
+
+### Preferences
+
+These options apply only to a given rendering mode of a Chord Chart.
+
+- **Chart Type**:
+    - **Complete**: renders everything
+    - **Lyrics only**: hide the chords
+    - **Chords only**: hide the lyrics
+    - **Chords + First lyric line**: display only the first lyric line of each section. Useful if you only need a quick reminder of the lyrics.
+- **Align chords with lyrics**: use the chord position markers in the lyric line to position the chords symbols above the lyrics
+- **Align bars**: align the chord symbols and the bar separators of all chord lines. This setting has no effect on chords symbols that are aligned with lyrics
+- **Auto repeat chords**: automatically repeat chords for identical sections (verse, chorus...).
+- **Expand copied sections**: when you repeat a section by using its label (`#c`, for ex), 
+use this setting to decide if only the section title should be printed or if the full section should be copied
+
+### Layout
+
+These options are only available in Screen view and Print Preview modes.
+
+- **Font size**: adjust the size of the text
+- **Columns**: display the song over multiple columns
+- **Column break on section**: avoid splitting a section in two different columns when printing a song
+- **Margins**: adjust the document margins when printing a song
+
+
diff --git a/packages/documentation/docs/licenses.md b/packages/documentation/docs/licenses.md
@@ -0,0 +1,9 @@
+# Licenses
+
+## Homepage icons
+
+[Creative commons Attribution CC BY](https://creativecommons.org/licenses/by/3.0/us/legalcode)
+
+- Lyrics by Konvisanu Suvannasri from [NounProject.com](https://thenounproject.com/)
+- Lightning by NeMaria from [NounProject.com](https://thenounproject.com/)
+- Swap by Adrien Coquet from [NounProject.com](https://thenounproject.com/)