Initialize the doc site

.pre-commit-config.yaml

@@ -2,14 +2,14 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.2.0
+    rev: v4.1.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-added-large-files
 
   - repo: https://github.com/psf/black
-    rev: 22.1.0
+    rev: 22.3.0
     hooks:
       - id: black
 
@@ -19,7 +19,7 @@ repos:
       - id: isort
 
   - repo: https://gitlab.com/pycqa/flake8
-    rev: 4.0.1
+    rev: 3.9.2
     hooks:
       - id: flake8
         additional_dependencies:

README.md

@@ -1,5 +1,7 @@
 # Monas
 
+<!--index start-->
+
 [![Tests](https://github.com/frostming/monas/workflows/Tests/badge.svg)](https://github.com/frostming/monas/actions?query=workflow%3Aci)
 [![pypi version](https://img.shields.io/pypi/v/monas.svg)](https://pypi.org/project/monas/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
@@ -11,14 +13,12 @@ Python monorepo made easy.
 
 ➡️ [Example Repository](https://github.com/frostming/monas-example-repo)
 
-## Features
+## About this project
 
-**Monas** is a tool to manage multiple Python projects in a single monorepo. It is mainly inspired by [Lerna](https://lerna.js.org/). It supports the following build systems:
+**Monas** is a tool to manage multiple Python projects in a single repository, or the so called ["Monorepo"](https://en.wikipedia.org/wiki/Monorepo).
+It is mainly inspired by [Lerna](https://lerna.js.org/). In a monorepo, some dependencies are shared across packages while others are different. When you change the code of one of these shared dependencies, you may want to run the test suite across all dependant packages. Monas makes the workflow easier.
 
-- [setuptools](https://setuptools.pypa.io/)
-- [pdm](https://pdm.fming.dev/)
-- [flit](https://flit.pypa.io/)
-- [hatch](https://ofek.dev/hatch/latest/)
+<!--index end-->
 
 ## Installation
 
@@ -27,13 +27,13 @@ Python monorepo made easy.
 It is recommended to install with `pipx`, if `pipx` haven't been installed yet, refer to the [pipx's docs](https://github.com/pipxproject/pipx)
 
 ```bash
-$ pipx install monas
+pipx install monas
 ```
 
 Alternatively, install with `pip` to the user site:
 
 ```bash
-$ python -m pip install --user monas
+python -m pip install --user monas
 ```
 
 ## To-do

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/changelog.md

@@ -0,0 +1,3 @@
+```{include} ../CHANGELOG.md
+
+```

docs/conf.py

@@ -0,0 +1,61 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Monas"
+copyright = "2022, Frost Ming"
+author = "Frost Ming"
+
+# The full version, including alpha/beta/rc tags
+release = "0.1.0"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.todo",
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_click",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]

docs/contributing.md

@@ -0,0 +1,3 @@
+```{include} ../CONTRIBUTING.md
+
+```

docs/index.md

@@ -0,0 +1,27 @@
+# Mono Documentation
+
+```{include} ../README.md
+:start-after: <!--index start-->
+:end-before: <!--index end-->
+```
+
+```{toctree}
+
+quickstart
+```
+
+```{toctree}
+:caption: CLI Reference
+
+reference
+```
+
+```{toctree}
+:caption: Development
+:hidden:
+
+changelog
+contributing
+GitHub <https://github.com/frostming/monas>
+PyPI <https://pypi.org/project/monas>
+```

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/quickstart.md

@@ -0,0 +1,67 @@
+# Quick Start
+
+## Install Monas
+
+**Monas** requires Python >=3.7.
+
+It is recommended to install with `pipx`, if `pipx` haven't been installed yet, refer to the [pipx's docs](https://github.com/pipxproject/pipx)
+
+```bash
+pipx install monas
+```
+
+Alternatively, install with `pip` to the user site:
+
+```bash
+python -m pip install --user monas
+```
+
+## Create a monorepo
+
+Monas is integrated with Git. You need to install it if it isn't on your system.
+
+```bash
+git init mono-project
+cd mono-project
+monas init
+```
+
+## Add a subpackage
+
+```bash
+monas new foo
+```
+
+Answer a few questions and the subpackage `foo` will be created under `packages/` directory.
+
+See what packages are added:
+
+```bash
+monas list
+```
+
+## Add dependencies to the subpackages
+
+```bash
+monas add click
+```
+
+The dependencies will be installed into the `.venv` folder under each subpackage.
+
+## Submit and push
+
+```bash
+git add .
+git commit -m "initial commit"
+git remote add origin <your repo url>
+git push -u origin main
+```
+
+## Bump version and Publish
+
+```bash
+monas bump
+monas publish
+```
+
+A git tag of the specified version together with a PyPI release will be published.

docs/reference.md

@@ -0,0 +1,7 @@
+# `monas`
+
+```{eval-rst}
+.. click:: monas.cli:main
+    :prog: monas
+    :nested: full
+```

docs/requirements.txt

@@ -0,0 +1,5 @@
+furo
+sphinx
+myst-parser
+sphinx-copybutton
+sphinx-click