Merge pull request #123 from mapillary/Rubix982/Docusaurus

[Documentation] `Docusaurus` instantiation

Author: Rubix982

.gitignore

@@ -141,4 +141,7 @@ dmypy.json
 cython_debug/
 
 # Testing
-tests/helper/data/*.geojson
+tests/helper/data/*.geojson
+
+# Sphinx documentation generation
+sphinx-docs/

Makefile

@@ -1,40 +1,101 @@
 # Copyright (c) Facebook, Inc. and its affiliates. (http://www.facebook.com)
 
 define PYTHON_SCRIPT
+
 import os
 import sys
+
 sys.path.insert(0, os.path.abspath('../'))
 
-def skip(app, what, name, obj,would_skip, options):
-	if name in ( '__init__',):
-		return False
-	return would_skip
 
-	def setup(app):
-		app.connect('autodoc-skip-member', skip)
-	extensions.append('sphinx_autodoc_typehints')
+def skip(app, what, name, obj, would_skip, options):
+    '''Skip'''
+
+    extensions.append('sphinx_autodoc_typehints')
+
+    if name in ('__init__',):
+        return False
+    return would_skip
+
+
+    def setup(app):
+        '''Setup App'''
+
+        app.connect('autodoc-skip-member', skip)
 endef
 
+# SETUP
+
+# # Setup all
+setup: setup-prod setup-dev
+
+# # Install needed dependencies
+setup-prod:
+	python -m pip install --upgrade pip
+	pip install pipenv
+	pipenv install
+
+# # Install developer dependencies
+setup-dev:
+	python -m pip install --upgrade pip
+	pip install pipenv
+	pipenv install --dev
+
+# PACKAGE BUILD
+
+# # Build the package
+build:
+	# Builds the package distributions
+	python3 setup.py sdist bdist_wheel --universal
+
+local-install:
+	# Locally install mapillary - DO THIS ONLY AFTER RUNNING `make build`
+	pip3 install -e .
+
+# CODE QUALITY
+
+# # Styling related
 style: format lint
 
+# # # Formatting
 format:
-	black src/mapillary
+	@ black src/mapillary
 
+# # # Linting
 lint:
-	# stop the build if there are Python syntax errors or undefined names
-	flake8 src/mapillary --count --select=E9,F63,F7,F82 --show-source --statistics
+	@ # stop the build if there are Python syntax errors or undefined names
+	@ flake8 src/mapillary --count --select=E9,F63,F7,F82 --show-source --statistics
+
+	@ # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+	@ flake8 src/mapillary --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
+# DOCUMENTATION
 
-	# exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-	flake8 src/mapillary --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+# # For generating the latest developer documentation from src/mapillary
+# # and serving them locally with Docusaurus
+docs-gen: docs-sphinx docs-py docs-start
 
-sphinx-docs:
+# # # Sphinx Documentation Generation
+docs-sphinx:
 	sphinx-apidoc -o sphinx-docs ./src/ sphinx-apidoc --full -A 'Mapillary'; cd sphinx-docs; echo "$$PYTHON_SCRIPT" >> conf.py; make markdown;
 
-sphinx-docs-clean:
-	rm -rf sphinx-docs/
+# # # Python Script for moving markdown from sphinx -> docusaurus
+docs-py:
+	python3 scripts/documentation.py
+
+# # # Serve the newly generated documentation
+docs-start:
+	cd docs; npm run start;
 
-docs: docs-build docs-deploy
+# # For pushing the docs to the gh-pages branch
+docs-push: docs-build docs-deploy
 
+# # # Building the static pages
+docs-build:
+	# Building the documentation
+	cd docs; npm run build;
+
+# # # Deploying the documentation to gh-pages
 docs-deploy:
 	# Deploying the documentation
 	# Deploying requires GIT_USER's password and write access to the repository
@@ -44,14 +105,25 @@ docs-deploy:
 	# https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/
 	cd docs; GIT_USER=Rubix982 yarn deploy;
 
-docs-build:
-	# Building the documentation
-	cd docs; npm run build;
+# CLEANING
+
+# # Removing temporary created artifacts
+clean: sphinx-docs-clean docs-clean build-clean
+
+# # # Remove Sphinx Documentation
+sphinx-docs-clean:
+	rm -rf sphinx-docs/
 
+# # # Remove latest build of docs
 docs-clean:
 	rm -rf docs/build
 
+# # # Remove latest sr/mapillary build
+build-clean:
+	rm -rf build/ dist/
+
+# TESTING
+
+# # Execute pytest on tests/
 test:
 	@ pytest --log-cli-level=20
-
-clean: sphinx-docs-clean docs-clean

docs/.eslintrc.js

@@ -0,0 +1,60 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+const OFF = 0;
+const WARNING = 1;
+const ERROR = 2;
+
+module.exports = {
+  root: true,
+  env: {
+    browser: true,
+    commonjs: true,
+    jest: true,
+    node: true,
+  },
+  parser: '@babel/eslint-parser',
+  parserOptions: {
+    allowImportExportEverywhere: true,
+  },
+  extends: ['airbnb', 'prettier', 'prettier/react'],
+  plugins: ['react-hooks', 'header'],
+  rules: {
+    // Ignore certain webpack alias because it can't be resolved
+    'import/no-unresolved': [
+      ERROR,
+      {ignore: ['^@theme', '^@docusaurus', '^@generated']},
+    ],
+    'import/extensions': OFF,
+    'header/header': [
+      ERROR,
+      'block',
+
+      [
+        '*',
+        ' * Copyright (c) Facebook, Inc. and its affiliates.',
+        ' *',
+        ' * This source code is licensed under the MIT license found in the',
+        ' * LICENSE file in the root directory of this source tree.',
+        ' *',
+        // Unfortunately eslint-plugin-header doesn't support optional lines.
+        // If you want to enforce your website JS files to have @flow or @format,
+        // modify these lines accordingly.
+        {
+          pattern: '.* @format',
+        },
+        ' ',
+      ],
+    ],
+    'react/jsx-closing-bracket-location': OFF, // Conflicts with Prettier.
+    'react/jsx-filename-extension': OFF,
+    'react-hooks/rules-of-hooks': ERROR,
+    'react/prop-types': OFF, // PropTypes aren't used much these days.
+  },
+};

docs/.gitignore

@@ -0,0 +1,23 @@
+# 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*
+
+# ESLint
+.eslintcache

docs/.prettierignore

@@ -0,0 +1,3 @@
+node_modules
+build
+.docusaurus

docs/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "arrowParens": "always",
+  "bracketSpacing": false,
+  "jsxBracketSameLine": true,
+  "printWidth": 80,
+  "proseWrap": "never",
+  "singleQuote": true,
+  "trailingComma": "all"
+}

docs/.stylelintrc.js

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+module.exports = {
+  plugins: ['stylelint-copyright'],
+  rules: {
+    'docusaurus/copyright-header': true,
+  },
+};

docs/README.md

@@ -0,0 +1,41 @@
+# 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.
+
+### Continuous Integration
+
+Some common defaults for linting/formatting have been set for you. If you integrate your project with an open source Continuous Integration system (e.g. Travis CI, CircleCI), you may check for issues using the following command.
+
+```
+$ yarn ci
+```

docs/babel.config.js

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/blog/2019-05-28-first-blog-post.md

@@ -0,0 +1,12 @@
+---
+slug: first-blog-post
+title: First Blog Post
+authors:
+  name: Gao Wei
+  title: Docusaurus Core Team
+  url: https://github.com/wgao19
+  image_url: https://github.com/wgao19.png
+tags: [hola, docusaurus]
+---
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet