merge template, fill vars, lint

docs/conf.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-#
 # py-libp2p documentation build configuration file, created by
 # sphinx-quickstart on Thu Oct 16 20:43:24 2014.
 #
@@ -19,7 +17,7 @@
 
 import os
 
-DIR = os.path.dirname("__file__")
+DIR = os.path.dirname(__file__)
 with open(os.path.join(DIR, "../setup.py"), "r") as f:
     for line in f:
         if "version=" in line:
@@ -200,6 +198,8 @@ htmlhelp_basename = "libp2pdocs"
 
 # -- Options for LaTeX output ---------------------------------------------
 
+latex_engine = "xelatex"
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #'papersize': 'letterpaper',

docs/contributing.rst

@@ -1,8 +1,12 @@
 Contributing
 ------------
 
-Development
-~~~~~~~~~~~
+Thank you for your interest in contributing! We welcome all contributions no matter
+their size. Please read along to learn how to get started. If you get stuck, feel free
+to ask for help in `Ethereum Python Discord server <https://discord.gg/GHryRvPB84>`_.
+
+Setting the stage
+~~~~~~~~~~~~~~~~~
 
 To get started, fork the repository to your own github account, then clone it to your
 development machine:
@@ -11,8 +15,7 @@ development machine:
 
     git clone git@github.com:your-github-username/py-libp2p.git
 
-
-then install the development dependencies. We recommend using a virtual environment,
+Next, install the development dependencies. We recommend using a virtual environment,
 such as `virtualenv <https://virtualenv.pypa.io/en/stable/>`_.
 
 .. code:: sh
@@ -43,12 +46,16 @@ Requirements
 The protobuf description in this repository was generated by ``protoc`` at version
 ``27.2``.
 
-Testing
-~~~~~~~
+Running the tests
+~~~~~~~~~~~~~~~~~
 
-Running that tests is a great way to explore the codebase.
+A great way to explore the code base is to run the tests.
 
-You can run all the tests with ``pytest tests``.
+We can run all tests with:
+
+.. code:: sh
+
+    make test
 
 At this time, the interop tests are not passing. You can run just the internal tests
 with ``pytest tests/core``.
@@ -57,20 +64,47 @@ with ``pytest tests/core``.
 Code Style
 ~~~~~~~~~~
 
-We use `pre-commit <https://pre-commit.com/>`_ to maintain consistent code style. Once
-installed, it will run automatically with every commit. You can also run it manually
-with:
+We use `pre-commit <https://pre-commit.com/>`_ to enforce a consistent code style across
+the library. This tool runs automatically with every commit, but you can also run it
+manually with:
 
 .. code:: sh
 
     make lint
 
-If you need to make a commit that skips the pre-commit checks, you can do so with
+If you need to make a commit that skips the ``pre-commit`` checks, you can do so with
 ``git commit --no-verify``.
 
-This project uses ``mypy`` for static type checking, though it is not yet complete.
-All new code should be fully typed, and we are working to add types to the existing
-codebase.
+This library uses type hints, which are enforced by the ``mypy`` tool (part of the
+``pre-commit`` checks). All new code is required to land with type hints, with the
+exception of code within the ``tests`` directory.
+
+Documentation
+~~~~~~~~~~~~~
+
+Good documentation will lead to quicker adoption and happier users. Please check out our
+guide on
+`how to create documentation for the Python Ethereum ecosystem <https://github.com/ethereum/snake-charmers-tactical-manual/blob/main/documentation.md>`_.
+
+Pull Requests
+~~~~~~~~~~~~~
+
+It's a good idea to make pull requests early on. A pull request represents the start of
+a discussion, and doesn't necessarily need to be the final, finished submission.
+
+GitHub's documentation for working on pull requests is
+`available here <https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_.
+
+Once you've made a pull request, take a look at the Circle CI build status in the
+GitHub interface and make sure all tests are passing. In general pull requests that
+do not pass the CI build yet won't get reviewed unless explicitly requested.
+
+If the pull request introduces changes that should be reflected in the release notes,
+please add a `newsfragment` file as explained
+`here <https://github.com/ethereum/py-libp2p/blob/main/newsfragments/README.md>`_.
+
+If possible, the change to the release notes file should be included in the commit that
+introduces the feature or bugfix.
 
 Releasing
 ~~~~~~~~~
@@ -87,10 +121,8 @@ Before releasing a new version, build and test the package that will be released
 .. code:: sh
 
     git checkout main && git pull
-
     make package-test
 
-
 This will build the package and install it in a temporary virtual environment. Follow
 the instructions to activate the venv and test whatever you think is important.
 
@@ -100,7 +132,6 @@ You can also preview the release notes:
 
     towncrier --draft
 
-
 Build the release notes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -112,7 +143,6 @@ release notes.
 
     make notes bump=$$VERSION_PART_TO_BUMP$$
 
-
 If there are any errors, be sure to re-run make notes until it works.
 
 Push the release to github & pypi
@@ -124,7 +154,6 @@ After confirming that the release package looks okay, release a new version:
 
     make release bump=$$VERSION_PART_TO_BUMP$$
 
-
 This command will:
 
 - Bump the version number as specified in ``.pyproject.toml`` and ``setup.py``.

docs/index.rst

@@ -3,8 +3,13 @@ py-libp2p
 
 The Python implementation of the libp2p networking stack
 
-Contents
---------
+Installation
+------------
+
+.. code-block:: bash
+
+    python -m pip install py-libp2p
+
 
 .. toctree::
     :maxdepth: 1
@@ -14,6 +19,9 @@ Contents
     quickstart
     release_notes
 
+.. toctree::
+    :maxdepth: 1
+    :caption: Community
 
 .. toctree::
     :maxdepth: 1