Skip to content

Commit a31f304

Browse files
cburgdorfcburgdorf
committed
Simplify and deduplicate README
1 parent f2d0d5d commit a31f304

File tree

3 files changed

+32
-121
lines changed

3 files changed

+32
-121
lines changed

‎README.md

Lines changed: 7 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@
33
[![Join the chat at https://gitter.im/ethereum/py-evm](https://badges.gitter.im/ethereum/py-evm.svg)](https://gitter.im/ethereum/py-evm)
44
[![Documentation Status](https://readthedocs.org/projects/py-evm/badge/?version=latest)](http://py-evm.readthedocs.io/en/latest/?badge=latest)
55

6-
[Documentation hosted by ReadTheDocs](http://py-evm.readthedocs.io/en/latest/)
7-
86

97
## Introducing Py-EVM
108

@@ -51,95 +49,15 @@ our architecture and API choices as well as general feedback and bug finding.
5149
- https://medium.com/@pipermerriam/py-evm-part-1-origins-25d9ad390b
5250

5351

54-
## Development
55-
Py-EVM depends on a submodule of the common tests across all clients,
56-
so you need to clone the repo with the `--recursive` flag. Example:
57-
58-
```sh
59-
git clone --recursive [email protected]:ethereum/py-evm.git
60-
```
61-
62-
Py-EVM requires Python 3. Often, the best way to guarantee a clean Python 3 environment is with [`virtualenv`](https://virtualenv.pypa.io/en/stable/), like:
63-
64-
```sh
65-
# once:
66-
$ virtualenv -p python3 venv
67-
68-
# each session:
69-
$ . venv/bin/activate
70-
```
71-
72-
Then install the required python packages via:
73-
74-
```sh
75-
pip install -e .[dev]
76-
```
77-
78-
79-
### Running the tests
80-
81-
You can run the tests with:
82-
83-
```sh
84-
pytest
85-
```
86-
87-
Or you can install `tox` to run the full test suite.
88-
89-
90-
### Releasing
91-
92-
Pandoc is required for transforming the markdown README to the proper format to
93-
render correctly on pypi.
94-
95-
For Debian-like systems:
96-
97-
```
98-
apt install pandoc
99-
```
100-
101-
Or on OSX:
102-
103-
```sh
104-
brew install pandoc
105-
```
106-
107-
To release a new version:
108-
109-
```sh
110-
bumpversion $$VERSION_PART_TO_BUMP$$
111-
git push && git push --tags
112-
make release
113-
```
114-
115-
To create a docker image:
116-
117-
```sh
118-
make create-docker-image version=<version>
119-
```
120-
121-
By default, this will create a new image with two tags pointing to it:
122-
- `ethereum/trinity:<version>` (explicit version)
123-
- `ethereum/trinity:latest` (latest until overwritten with a future "latest")
124-
125-
Then, push to docker hub.
126-
127-
```sh
128-
docker push ethereum/trinity:<version>
129-
# the following may be left out if we were pushing a patch for an older version
130-
docker push ethereum/trinity:latest
131-
```
132-
52+
## Quickstart
13353

134-
#### How to bumpversion
54+
[Get started in 5 minutes](https://py-evm.readthedocs.io/en/latest/quickstart.html)
13555

136-
The version format for this repo is `{major}.{minor}.{patch}` for stable, and
137-
`{major}.{minor}.{patch}-{stage}.{devnum}` for unstable (`stage` can be alpha or beta).
56+
## Documentation
13857

139-
To issue the next version in line, use bumpversion and specify which part to bump,
140-
like `bumpversion minor` or `bumpversion devnum`.
58+
Check out the [documentation on our official website](http://py-evm.readthedocs.io/en/latest/)
14159

142-
If you are in a beta version, `bumpversion stage` will switch to a stable.
60+
## Want to help?
14361

144-
To issue an unstable version when the current version is stable, specify the
145-
new version explicitly, like `bumpversion --new-version 4.0.0-alpha.1 devnum`
62+
Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on our
63+
guidelines for [contributing](https://py-evm.readthedocs.io/en/latest/contributing.html) and then check out one of our issues that are labeled [Good First Issue](https://github.com/ethereum/py-evm/issues?q=is%3Aissue+is%3Aopen+label%3A%22Good+First+Issue%22).

‎docs/contributing.rst

Lines changed: 23 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -72,37 +72,9 @@ All parameters as well as the return type of defs are expected to be typed with
7272
Documentation
7373
~~~~~~~~~~~~~
7474

75-
Public APIs are expected to be annotated with docstrings as seen in the following example.
75+
Good documentation will lead to quicker adoption and happier users. Please check out our guide
76+
on `how to create documentation for the Python Ethereum ecosystem <https://github.com/ethereum/snake-charmers-tactical-manual/blob/master/documentation.md>`_.
7677

77-
.. code:: python
78-
79-
def add_transaction(self,
80-
transaction: BaseTransaction,
81-
computation: BaseComputation,
82-
block: BaseBlock) -> Tuple[Block, Dict[bytes, bytes]]:
83-
"""
84-
Add a transaction to the given block and
85-
return `trie_data` to store the transaction data in chaindb in VM layer.
86-
87-
Update the bloom_filter, transaction trie and receipt trie roots, bloom_filter,
88-
bloom, and used_gas of the block.
89-
90-
:param transaction: the executed transaction
91-
:param computation: the Computation object with executed result
92-
:param block: the Block which the transaction is added in
93-
94-
:return: the block and the trie_data
95-
"""
96-
97-
Docstrings are written in reStructuredText and allow certain type of directives.
98-
99-
Notice that ``:param:`` and ``:return:`` directives are being used to describe parameters and return value. Usage of ``:type:`` and ``:rtype:`` directives on the other hand is discouraged as sphinx directly reads and displays the types from the source code type definitions making any further use of ``:type:`` and ``:rtype:`` obsolete and unnecessarily verbose.
100-
101-
Use imperative, present tense to describe APIs: “return” not “returns”
102-
103-
One way to test if you have it right is to complete the following sentence.
104-
105-
If you call this API it will: __________________________
10678

10779
Pull Requests
10880
~~~~~~~~~~~~~
@@ -160,3 +132,24 @@ the new version explicitly, like
160132
``bumpversion --new-version 4.0.0-alpha.1 devnum``
161133

162134

135+
How to release docker images
136+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
137+
138+
To create a docker image:
139+
140+
.. code:: sh
141+
142+
make create-docker-image version=<version>
143+
144+
145+
By default, this will create a new image with two tags pointing to it:
146+
- ``ethereum/trinity:<version>`` (explicit version)
147+
- ``ethereum/trinity:latest`` (latest until overwritten with a future "latest")
148+
149+
Then, push to docker hub:
150+
151+
.. code:: sh
152+
153+
docker push ethereum/trinity:<version>
154+
# the following may be left out if we were pushing a patch for an older version
155+
docker push ethereum/trinity:latest

‎docs/guides/trinity/quickstart.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,8 @@ changes need to be made to the host system apart from having ``Docker`` itself i
6161

6262
.. note::
6363
While we don't officially support Windows just yet, running Trinity through ``Docker`` is a great
64-
way to bypass this current limitation as Trinity can run on any system that runs ``Docker`` [with
65-
support for linux containers](https://docs.docker.com/docker-for-windows/#switch-between-windows-and-linux-containers).
64+
way to bypass this current limitation as Trinity can run on any system that runs ``Docker`` `with
65+
support for linux containers <https://docs.docker.com/docker-for-windows/#switch-between-windows-and-linux-containers>`_.
6666

6767
Using ``Docker`` we have two different options to choose from.
6868

0 commit comments

Comments
 (0)