-
Notifications
You must be signed in to change notification settings - Fork 104
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add documentation #330
Closed
Closed
Add documentation #330
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
7442d3f
Add basic autodoc and doc file structure
dmuhs 3621f0b
Fix formatting in docs conf
dmuhs fc65511
Fix unexpected indentation warning in Swarm.listen docstring
dmuhs 78aa5f9
Add installation notes
dmuhs 3d13153
Fix mypy errors
dmuhs f7403ef
Add setup.py doc extra
dmuhs d4808a6
Merge branch 'master' of github.com:libp2p/py-libp2p
dmuhs 817e9c8
Add docs to extra dev requirements
dmuhs File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 = source | ||
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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
@ECHO OFF | ||
|
||
pushd %~dp0 | ||
|
||
REM Command file for Sphinx documentation | ||
|
||
if "%SPHINXBUILD%" == "" ( | ||
set SPHINXBUILD=sphinx-build | ||
) | ||
set SOURCEDIR=source | ||
set BUILDDIR=build | ||
|
||
if "%1" == "" goto help | ||
|
||
%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.http://sphinx-doc.org/ | ||
exit /b 1 | ||
) | ||
|
||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
goto end | ||
|
||
:help | ||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
|
||
:end | ||
popd |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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: | ||
# http://www.sphinx-doc.org/en/master/config | ||
|
||
# -- 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 = "py-libp2p" | ||
copyright = "2019, The py-libp2p team" | ||
author = "The py-libp2p team" | ||
|
||
# The full version, including alpha/beta/rc tags | ||
release = "0.1.1" | ||
|
||
|
||
# -- 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.coverage", | ||
"sphinx.ext.napoleon", | ||
"sphinx.ext.viewcode", | ||
"sphinx.ext.coverage", | ||
] | ||
|
||
# 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 = [] | ||
|
||
|
||
# -- 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 = "sphinx_rtd_theme" | ||
|
||
# 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"] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
Welcome to py-libp2p's documentation! | ||
===================================== | ||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
:caption: Contents: | ||
|
||
installation | ||
libp2p/index.rst | ||
|
||
|
||
Indices and tables | ||
================== | ||
|
||
* :ref:`genindex` | ||
* :ref:`modindex` | ||
* :ref:`search` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
.. highlight:: shell | ||
|
||
Installation | ||
============ | ||
|
||
Stable release | ||
-------------- | ||
|
||
To install :code:`py-libp2p`:, run this command in your terminal: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There's no right or wrong when it comes to the narrative perspective but we chose to use the first-person "we" form which means there is rarely ever a place for "you" in our docs. E.g. see Trinity's quickstart written in first person "we" form |
||
|
||
.. code-block:: console | ||
|
||
$ pip install libp2p | ||
|
||
This is the preferred method to install the library, as it will always install | ||
the most recent stable release. | ||
|
||
If you don't have `pip`_ installed, this `Python installation guide`_ can guide | ||
you through the process. | ||
|
||
.. _pip: https://pip.pypa.io | ||
.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/ | ||
|
||
|
||
From sources | ||
------------ | ||
|
||
The sources for :code:`py-libp2p` can be downloaded from the `Github repo`_. | ||
|
||
You can either clone the public repository: | ||
|
||
.. code-block:: console | ||
|
||
$ git clone git://github.com/libp2p/py-libp2p | ||
|
||
Or download the `tarball`_: | ||
|
||
.. code-block:: console | ||
|
||
$ curl -OL https://github.com/libp2p/py-libp2p/tarball/master | ||
|
||
Once you have a copy of the source, you can install it with: | ||
|
||
.. code-block:: console | ||
|
||
$ python setup.py install | ||
|
||
|
||
.. _Github repo: https://github.com/libp2p/py-libp2p | ||
.. _tarball: https://github.com/libp2p/py-libp2p/tarball/master |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.crypto.authenticated_encryption | ||
====================================== | ||
|
||
.. automodule:: libp2p.crypto.authenticated_encryption | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.crypto.ecc | ||
================= | ||
|
||
.. automodule:: libp2p.crypto.ecc | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.crypto.ed25519 | ||
====================== | ||
|
||
.. automodule:: libp2p.crypto.ed25519 | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.crypto.exceptions | ||
======================== | ||
|
||
.. automodule:: libp2p.crypto.exceptions | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,14 @@ | ||
libp2p.crypto | ||
============= | ||
|
||
.. toctree:: | ||
authenticated_encryption.rst | ||
ecc.rst | ||
ed25519.rst | ||
exceptions.rst | ||
key_exchange.rst | ||
keys.rst | ||
rsa.rst | ||
secp256k1.rst | ||
serialization.rst | ||
pb/crypto_pb2.rst |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.crypto.key_exchange | ||
========================== | ||
|
||
.. automodule:: libp2p.crypto.key_exchange | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.crypto.keys | ||
================== | ||
|
||
.. automodule:: libp2p.crypto.keys | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.crypto.pb.crypto_pb2 | ||
=========================== | ||
|
||
.. automodule:: libp2p.crypto.pb.crypto_pb2 | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.crypto.rsa | ||
================= | ||
|
||
.. automodule:: libp2p.crypto.rsa | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.crypto.secp256k1 | ||
======================= | ||
|
||
.. automodule:: libp2p.crypto.secp256k1 | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.crypto.serialization | ||
=========================== | ||
|
||
.. automodule:: libp2p.crypto.serialization | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.exceptions | ||
================= | ||
|
||
.. automodule:: libp2p.exceptions | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.host.basic_host | ||
====================== | ||
|
||
.. automodule:: libp2p.host.basic_host | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.host.exceptions | ||
====================== | ||
|
||
.. automodule:: libp2p.host.exceptions | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.host.host_interface | ||
========================== | ||
|
||
.. automodule:: libp2p.host.host_interface | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
libp2p.host | ||
=========== | ||
|
||
.. toctree:: | ||
basic_host.rst | ||
exceptions.rst | ||
host_interface.rst | ||
routed_host.rst |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.host.routed_host | ||
======================= | ||
|
||
.. automodule:: libp2p.host.routed_host | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
libp2p module | ||
============= | ||
|
||
Subpackages | ||
----------- | ||
|
||
.. toctree:: | ||
crypto/index.rst | ||
host/index.rst | ||
io/index.rst | ||
kademlia/index.rst | ||
network/index.rst | ||
peer/index.rst | ||
protocol_muxer/index.rst | ||
pubsub/index.rst | ||
routing/index.rst | ||
security/index.rst | ||
stream_muxer/index.rst | ||
transport/index.rst | ||
exceptions.rst | ||
typing.rst |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.io.abc | ||
============= | ||
|
||
.. automodule:: libp2p.io.abc | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.io.exceptions | ||
==================== | ||
|
||
.. automodule:: libp2p.io.exceptions | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
libp2p.io | ||
========= | ||
|
||
.. toctree:: | ||
abc.rst | ||
exceptions.rst | ||
msgio.rst | ||
utils.rst |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.io.msgio | ||
=============== | ||
|
||
.. automodule:: libp2p.io.msgio | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
libp2p.io.utils | ||
=============== | ||
|
||
.. automodule:: libp2p.io.utils | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We have a few general documentation guidelines, and we're trying to make sure that all our repos are as close to them as possible.
That's why I'm taking this opportunity to point this out so that we can get these policies involved early on.
It's far from perfect but the project closest to the ideals of this guide line is probably Trinity so I recommend to take a look at its docs.
In particular, it would be nice if we could roughly follow this navigation structure.
General
Introduction: The landing page, giving a quick overview about the project, additional pointers.
Quickstart: Pretty much what you already have with all the installation instructions
Release Notes: Points to the towncrier generated release notes
Fundamentals
API: Source generated API docs as you already have them included in the PR
Cookbook: Collection of small recipes, examples. Doesn't need to exist in the beginning
Guides: Tutorial style guides. It's ok to just have a link to the Quickstart here to begin with
Community
Contributing: Instructions on how to contribute to the project
Code of Conduct: The code of conduct that we use across repos