Merge pull request #669 from messense/guide-develop

Write guide for local development

.codespellrc

@@ -0,0 +1,2 @@
+[codespell]
+ignore-words-list = crate

.github/workflows/lint.yml

@@ -47,6 +47,9 @@ jobs:
       - uses: psf/black@21.4b0
         with:
           args: ". --check"
+
+  spellcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
       - uses: codespell-project/actions-codespell@master
-        with:
-          ignore_words_list: crate

Readme.md

@@ -435,11 +435,12 @@ OPTIONS:
 
 ### Upload
 
-```
 Uploads python packages to pypi
 
 It is mostly similar to `twine upload`, but can only upload python wheels and source distributions.
 
+
+```
 USAGE:
     maturin upload [FLAGS] [OPTIONS] [FILE]...
 
@@ -468,7 +469,6 @@ OPTIONS:
 ARGS:
     <FILE>...
             The python packages to upload
-
 ```
 
 ## Code

guide/src/develop.md

@@ -1,3 +1,66 @@
 # Local Development
 
-TODO
+## `maturin develop` command
+
+For local development, the `maturin develop` command can be used to quickly
+build a package in debug mode by default and install it to virtualenv.
+
+```
+USAGE:
+    maturin develop [FLAGS] [OPTIONS]
+
+FLAGS:
+    -h, --help
+            Prints help information
+
+        --release
+            Pass --release to cargo
+
+        --strip
+            Strip the library for minimum file size
+
+    -V, --version
+            Prints version information
+
+
+OPTIONS:
+    -b, --binding-crate <binding-crate>
+            Which kind of bindings to use. Possible values are pyo3, rust-cpython, cffi and bin
+
+        --cargo-extra-args <cargo-extra-args>...
+            Extra arguments that will be passed to cargo as `cargo rustc [...] [arg1] [arg2] --`
+
+            Use as `--cargo-extra-args="--my-arg"`
+    -E, --extras <extras>
+            Install extra requires aka. optional dependencies
+
+            Use as `--extras=extra1,extra2`
+    -m, --manifest-path <manifest-path>
+            The path to the Cargo.toml [default: Cargo.toml]
+
+        --rustc-extra-args <rustc-extra-args>...
+            Extra arguments that will be passed to rustc as `cargo rustc [...] -- [arg1] [arg2]`
+
+            Use as `--rustc-extra-args="--my-arg"`
+```
+
+## PEP 660 Editable Installs
+
+Maturin supports [PEP 660](https://www.python.org/dev/peps/pep-0660/) editable installs since v0.12.0.
+You need to add `maturin` to `build-system` section of `pyproject.toml` to use it:
+
+```toml
+[build-system]
+requires = ["maturin>=0.12,<0.13"]
+build-backend = "maturin"
+```
+
+Editable installs right now is only useful in mixed Rust/Python project so you
+don't have to recompile and reinstall when only Python source code changes. For
+example when using pip you can make an editable installation with
+
+```bash
+pip install -e .
+```
+
+Then Python source code changes will take effect immediately.

test-crates/update_readme.py

@@ -4,30 +4,40 @@
 from pathlib import Path
 
 
+FILES = [
+    "Readme.md",
+    "guide/src/develop.md",
+]
+
+
 def main():
     root = Path(
         subprocess.check_output(
             ["git", "rev-parse", "--show-toplevel"], text=True
         ).strip()
     )
 
-    readme = root.joinpath("Readme.md").read_text()
+    for path in FILES:
+        content = root.joinpath(path).read_text()
 
-    matcher = re.compile(r"### (\w+)\n\n```\n(USAGE:.*?)```", re.MULTILINE | re.DOTALL)
-
-    replaces = {}
-    for command, old in matcher.findall(readme):
-        command_output = subprocess.check_output(
-            ["cargo", "run", "--", command.lower(), "--help"], text=True
+        matcher = re.compile(
+            r"```\nUSAGE:\n    maturin (\w+) (.*?)```", re.MULTILINE | re.DOTALL
         )
-        new = "USAGE:" + command_output.strip().split("USAGE:")[1] + "\n"
-        # Remove trailing whitespace
-        new = re.sub(" +\n", "\n", new)
-        replaces[old] = new
-
-    for old, new in replaces.items():
-        readme = readme.replace(old, new)
-    root.joinpath("Readme.md").write_text(readme)
+
+        replaces = {}
+        for command, old in matcher.findall(content):
+            command_output = subprocess.check_output(
+                ["cargo", "run", "--", command.lower(), "--help"], text=True
+            )
+            new = "USAGE:" + command_output.strip().split("USAGE:")[1] + "\n"
+            # Remove trailing whitespace
+            new = re.sub(" +\n", "\n", new)
+            old = "USAGE:\n    maturin " + command + " " + old
+            replaces[old] = new
+
+        for old, new in replaces.items():
+            content = content.replace(old, new)
+        root.joinpath(path).write_text(content)
 
 
 if __name__ == "__main__":