Merge pull request RustPython#1154 from RustPython/coolreader18/update-readmes

windelbouwman · web-flow · commit 19e783d28511 · 2019-07-17T09:30:33.000+02:00
Update READMEs
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Shing Lyu
+Copyright (c) 2019 RustPython Team
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/Lib/README.md b/Lib/README.md
@@ -1,10 +1,13 @@
-Standard Library for RustPython
-===============================
+# Standard Library for RustPython
 
-This directory contains all of the Python files that make up the standard library for RustPython.
+This directory contains all of the Python files that make up the standard
+library for RustPython.
 
-Most of these files are copied over from the CPython repository(the 3.7 branch), with slight modifications to allow them 
-to work under RustPython. The current goal is to complete the standard library with as few modifications as possible. 
-Current modifications are just temporary workarounds for bugs/missing feature within the RustPython implementation.
+Most of these files are copied over from the CPython repository (the 3.7
+branch), with slight modifications to allow them to work under RustPython. The
+current goal is to complete the standard library with as few modifications as
+possible. Current modifications are just temporary workarounds for bugs/missing
+feature within the RustPython implementation.
 
-The first target is to run the ``unittest`` module, so we can leverage the CPython test suite.
+The first big module we are targeting is `unittest`, so we can leverage the
+CPython test suite.
diff --git a/README.md b/README.md
@@ -2,7 +2,8 @@
 
 # RustPython
 
-A Python-3 (CPython >= 3.5.0) Interpreter written in Rust :snake: :scream: :metal:.
+A Python-3 (CPython >= 3.5.0) Interpreter written in Rust :snake: :scream:
+:metal:.
 
 [![Build Status](https://travis-ci.org/RustPython/RustPython.svg?branch=master)](https://travis-ci.org/RustPython/RustPython)
 [![Build Status](https://dev.azure.com/ryan0463/ryan/_apis/build/status/RustPython.RustPython?branchName=master)](https://dev.azure.com/ryan0463/ryan/_build/latest?definitionId=1&branchName=master)
@@ -11,9 +12,9 @@ A Python-3 (CPython >= 3.5.0) Interpreter written in Rust :snake: :scream: :meta
 [![Contributors](https://img.shields.io/github/contributors/RustPython/RustPython.svg)](https://github.com/RustPython/RustPython/graphs/contributors)
 [![Gitter](https://badges.gitter.im/RustPython/Lobby.svg)](https://gitter.im/rustpython/Lobby)
 
-# Usage
+## Usage
 
-### Check out our [online demo](https://rustpython.github.io/demo/) running on WebAssembly.
+#### Check out our [online demo](https://rustpython.github.io/demo/) running on WebAssembly.
 
 To test RustPython, do the following:
 
@@ -29,38 +30,44 @@ Or use the interactive shell:
     >>>>> 2+2
     4
 
-# Disclaimer
+## Disclaimer
 
-  RustPython is in a development phase and should not be used in production or a fault intolerant setting.
+RustPython is in a development phase and should not be used in production or a
+fault intolerant setting.
 
-  Our current build supports only a subset of Python syntax.
+Our current build supports only a subset of Python syntax.
 
-  Contribution is also more than welcome! See our contribution section for more information on this. 
+Contribution is also more than welcome! See our contribution section for more
+information on this.
 
-# Conference videos
+## Conference videos
 
 Checkout those talks on conferences:
 
 - [FOSDEM 2019](https://www.youtube.com/watch?v=nJDY9ASuiLc)
 - [EuroPython 2018](https://www.youtube.com/watch?v=YMmio0JHy_Y)
 
-# Use cases
+## Use cases
 
 Allthough rustpython is a very young project, it is already used in the wild:
 
-- [pyckitup](https://github.com/pickitup247/pyckitup): a game engine written in rust.
-- [codingworkshops.org](https://github.com/chicode/codingworkshops): a site where you can learn how to code.
+- [pyckitup](https://github.com/pickitup247/pyckitup): a game engine written in
+  rust.
+- [codingworkshops.org](https://github.com/chicode/codingworkshops): a site
+  where you can learn how to code.
 
-# Goals
+## Goals
 
 - Full Python-3 environment entirely in Rust (not CPython bindings)
 - A clean implementation without compatibility hacks
 
-# Documentation
+## Documentation
 
-Currently along with other areas of the project, documentation is still in an early phase.
+Currently along with other areas of the project, documentation is still in an
+early phase.
 
-You can read the [online documentation](https://rustpython.github.io/website/rustpython/index.html) for the latest code on master.
+You can read the [online documentation](https://docs.rs/rustpython-vm) for the
+latest release.
 
 You can also generate documentation locally by running:
 
@@ -71,29 +78,28 @@ $ cargo doc --no-deps --all # Excluding all dependencies
 
 Documentation HTML files can then be found in the `target/doc` directory.
 
-If you wish to update the online documentation, push directly to the `release` branch (or ask a maintainer to do so). This will trigger a Travis build that updates the documentation and WebAssembly demo page.
+## Contributing
 
-# Contributing
+Contributions are more than welcome, and in many cases we are happy to guide
+contributors through PRs or on gitter.
 
-Contributions are more than welcome, and in many cases we are happy to guide contributors through PRs or on gitter.
+With that in mind, please note this project is maintained by volunteers, some of
+the best ways to get started are below:
 
-With that in mind, please note this project is maintained by volunteers, some of the best ways to get started are below:
+Most tasks are listed in the
+[issue tracker](https://github.com/RustPython/RustPython/issues). Check issues
+labeled with `good first issue` if you wish to start coding.
 
-Most tasks are listed in the [issue tracker](https://github.com/RustPython/RustPython/issues).
-Check issues labeled with `good first issue` if you wish to start coding.
+Another approach is to checkout the source code: builtin functions and object
+methods are often the simplest and easiest way to contribute.
 
-Another approach is to checkout the source code: builtin functions and object methods are often the simplest
-and easiest way to contribute.
+You can also simply run `./whats_left.sh` to assist in finding any unimplemented
+method.
 
-You can also simply run
-`./whats_left.sh` to assist in finding any
-unimplemented method.
+## Using a standard library
 
-# Using a standard library
-
-As of now the standard library is under construction. You can
-use a standard library by setting the RUSTPYTHONPATH environment
-variable.
+As of now the standard library is under construction. You can use a standard
+library by setting the RUSTPYTHONPATH environment variable.
 
 To do this, follow this method:
 
@@ -102,32 +108,38 @@ $ export RUSTPYTHONPATH=~/GIT/RustPython/Lib
 $ cargo run -- -c 'import xdrlib'
 ```
 
-You can play around
-with other standard libraries for python. For example,
-the [ouroboros library](https://github.com/pybee/ouroboros).
+You can play around with other standard libraries for python. For example, the
+[ouroboros library](https://github.com/pybee/ouroboros).
 
-# Compiling to WebAssembly
+## Compiling to WebAssembly
 
 [See this doc](wasm/README.md)
 
-# Community
+## Community
 
 Chat with us on [gitter][gitter].
 
-# Code of conduct
+## Code of conduct
 
 Our code of conduct [can be found here](code-of-conduct.md).
 
-# Credit
+## Credit
 
-The initial work was based on [windelbouwman/rspython](https://github.com/windelbouwman/rspython) and [shinglyu/RustPython](https://github.com/shinglyu/RustPython)
+The initial work was based on
+[windelbouwman/rspython](https://github.com/windelbouwman/rspython) and
+[shinglyu/RustPython](https://github.com/shinglyu/RustPython)
 
 [gitter]: https://gitter.im/rustpython/Lobby
 
-# Links
+## Links
 
 These are some useful links to related projects:
 
 - https://github.com/ProgVal/pythonvm-rust
 - https://github.com/shinglyu/RustPython
 - https://github.com/windelbouwman/rspython
+
+## License
+
+This project is licensed under the MIT license. Please see the
+[LICENSE](LICENSE) file for more details.
diff --git a/benchmarks/README.md b/benchmarks/README.md
@@ -1,9 +1,8 @@
-
 # Benchmarking
 
 These are some files to determine performance of rustpython.
 
-# Usage
+## Usage
 
 Install pytest and pytest-benchmark:
 
@@ -13,7 +12,11 @@ Then run:
 
     $ pytest
 
-# Benchmark source
+You can also benchmark the Rust benchmarks by just running
+`cargo +nightly bench` from the root of the repository. Make sure you have Rust
+nightly installed, as the benchmarking parts of the standard library are still
+unstable.
 
-- https://benchmarksgame-team.pages.debian.net/benchmarksgame/program/nbody-python3-2.html
+## Benchmark source
 
+- https://benchmarksgame-team.pages.debian.net/benchmarksgame/program/nbody-python3-2.html
diff --git a/benchmarks/bench.rs b/benchmarks/bench.rs
@@ -5,8 +5,9 @@ extern crate rustpython_parser;
 extern crate rustpython_vm;
 extern crate test;
 
+use rustpython_compiler::compile;
 use rustpython_vm::pyobject::PyResult;
-use rustpython_vm::{compile, VirtualMachine};
+use rustpython_vm::VirtualMachine;
 
 #[bench]
 fn bench_tokenization(b: &mut test::Bencher) {
@@ -91,7 +92,7 @@ fn bench_rustpy_nbody(b: &mut test::Bencher) {
     // NOTE: Take long time.
     let source = include_str!("./benchmarks/nbody.py");
 
-    let vm = VirtualMachine::new();
+    let vm = VirtualMachine::default();
 
     let code = match vm.compile(source, &compile::Mode::Single, "<stdin>".to_string()) {
         Ok(code) => code,
@@ -110,7 +111,7 @@ fn bench_rustpy_mandelbrot(b: &mut test::Bencher) {
     // NOTE: Take long time.
     let source = include_str!("./benchmarks/mandelbrot.py");
 
-    let vm = VirtualMachine::new();
+    let vm = VirtualMachine::default();
 
     let code = match vm.compile(source, &compile::Mode::Single, "<stdin>".to_string()) {
         Ok(code) => code,
diff --git a/benchmarks/test_benchmarks.py b/benchmarks/test_benchmarks.py
@@ -5,8 +5,6 @@
 import pytest
 import subprocess
 
-from benchmarks import nbody
-
 # Interpreters:
 rustpython_exe = '../target/release/rustpython'
 cpython_exe = sys.executable
diff --git a/tests/README.md b/tests/README.md
@@ -1,20 +1,18 @@
 # Test snippets
 
-This directory contains two sets of test snippets which can be run in
-Python.  The `snippets/` directory contains functional tests, and the
-`benchmarks/` directory contains snippets for use in benchmarking
-RustPython's performance.
+This directory contains two sets of test snippets which can be run in Python.
+The `snippets/` directory contains functional tests, and the `benchmarks/`
+directory contains snippets for use in benchmarking RustPython's performance.
 
-## Generates the test for not implemented methods
+## Setup
 
-run using cpython not_impl_gen.py it automatically generate a
-test snippet to check not yet implemented methods
+Our testing depends on [pytest](https://pytest.org), which you can either
+install globally using pip or locally using our
+[pipenv](https://docs.pipenv.org).
 
-## Running with CPython + RustPython
+## Running
 
-One way to run these snippets is by using CPython to do the parsing and
-compilation to bytecode. When this is done, run the bytecode with rustpython.
-
-## Running with RustPython
-
-The other option is to run all snippets with RustPython.
+Simply run `pytest` in this directory, and the tests should run (and hopefully
+pass). If it hangs for a long time, that's because it's building RustPython in
+release mode, which should take less time than it would to run every test
+snippet with RustPython compiled in debug mode.
diff --git a/wasm/README.md b/wasm/README.md
@@ -1,11 +1,15 @@
-
 # Compiling to webassembly
 
-At this stage RustPython only has preliminary support for web assembly. The instructions here are intended for developers or those wishing to run a toy example.
+At this stage RustPython only has preliminary support for web assembly. The
+instructions here are intended for developers or those wishing to run a toy
+example.
 
 ## Setup
 
-To get started, install [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/) and `npm`. ([wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/whirlwind-tour/basic-usage.html) should be installed by `wasm-pack`. if not, install it yourself)
+To get started, install
+[wasm-pack](https://rustwasm.github.io/wasm-pack/installer/) and `npm`.
+([wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/whirlwind-tour/basic-usage.html)
+should be installed by `wasm-pack`. if not, install it yourself)
 
 <!-- Using `rustup` add the compile target `wasm32-unknown-emscripten`. To do so you will need to have [rustup](https://rustup.rs/) installed.
 
@@ -25,26 +29,26 @@ cd emsdk-portable/
 
 ## Build
 
-Move into the `wasm` directory. This directory contains a library crate for interop
-with python to rust to js and back in `wasm/lib`, the demo website found at
-https://rustpython.github.io/demo in `wasm/demo`, and an example of how to use
-the crate as a library in one's own JS app in `wasm/example`.
+Move into the `wasm` directory. This directory contains a library crate for
+interop with python to rust to js and back in `wasm/lib`, the demo website found
+at https://rustpython.github.io/demo in `wasm/demo`, and an example of how to
+use the crate as a library in one's own JS app in `wasm/example`.
 
 ```sh
 cd wasm
 ```
 
-Go to the demo directory. This is the best way of seeing the changes made to either
-the library or the JS demo, as the `rustpython_wasm` module is set to the global
-JS variable `rp` on the website.
+Go to the demo directory. This is the best way of seeing the changes made to
+either the library or the JS demo, as the `rustpython_wasm` module is set to the
+global JS variable `rp` on the website.
 
 ```sh
 cd demo
 ```
 
-Now, start the webpack development server. It'll compile the crate and then
-the demo app. This will likely take a long time, both the wasm-pack portion and
-the webpack portion (from after it says "Your crate has been correctly compiled"),
+Now, start the webpack development server. It'll compile the crate and then the
+demo app. This will likely take a long time, both the wasm-pack portion and the
+webpack portion (from after it says "Your crate has been correctly compiled"),
 so be patient.
 
 ```sh
@@ -56,17 +60,24 @@ the text box or browser devtools with:
 
 ```js
 rp.pyEval(
-  `
+    `
 print(js_vars['a'] * 9)
 `,
-  {
-    vars: {
-      a: 9
+    {
+        vars: {
+            a: 9
+        }
     }
-  }
 );
 ```
 
-Alternatively, you can run `npm run build` to build the app once, without watching
-for changes, or `npm run dist` to build the app in release mode, both for the
-crate and webpack.
+Alternatively, you can run `npm run build` to build the app once, without
+watching for changes, or `npm run dist` to build the app in release mode, both
+for the crate and webpack.
+
+## Updating the demo
+
+If you wish to update the WebAssembly demo,
+[open a pull request](https://github.com/RustPython/RustPython/compare/release...master)
+to merge `master` into the `release` branch. This will trigger a Travis build
+that updates the demo page.
diff --git a/wasm/lib/README.md b/wasm/lib/README.md
@@ -13,7 +13,7 @@ A Python-3 (CPython >= 3.5.0) Interpreter written in Rust.
 
 ## Usage
 
-### Check out our [online demo](https://rustpython.github.io/demo/) running on WebAssembly.
+#### Check out our [online demo](https://rustpython.github.io/demo/) running on WebAssembly.
 
 ## Goals
 
