Add documentation #330

dmuhs · 2019-10-23T15:48:25Z

This PR will

add Sphinx as a documentation system
update the docs with autodoc instructions for all components of the code base
add basic installation instructions to the docs
fix a minor indentation issue in the Swarm.listen docstring

With this PR merged, documentation can be built locally by entering the docs folder and using the Makefile:

cd docs && make html

The output can be found in the build directory, in the case of html docs, it can be opened at docs/build/html/index.html. A variety of other documentation formats are available and can be checked out by using the Makefile's help command:

$ make help
Sphinx v2.2.0
Please use `make target' where target is one of
  html        to make standalone HTML files
  dirhtml     to make HTML files named index.html in directories
  singlehtml  to make a single large HTML file
  pickle      to make pickle files
  json        to make JSON files
  htmlhelp    to make HTML files and an HTML help project
  qthelp      to make HTML files and a qthelp project
  devhelp     to make HTML files and a Devhelp project
  epub        to make an epub
  latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  latexpdf    to make LaTeX and PDF files (default pdflatex)
  latexpdfja  to make LaTeX files and run them through platex/dvipdfmx
  text        to make text files
  man         to make manual pages
  texinfo     to make Texinfo files
  info        to make Texinfo files and run them through makeinfo
  gettext     to make PO message catalogs
  changes     to make an overview of all changed/added/deprecated items
  xml         to make Docutils-native XML files
  pseudoxml   to make pseudoxml-XML files for display purposes
  linkcheck   to check all external links for integrity
  doctest     to run all doctests embedded in the documentation (if enabled)
  coverage    to run coverage check of the documentation (if enabled)

New documentation can be added by simply manipulating the code components' docstrings, or explicitly by editing the rst files in the docs folder. These files mirror 1:1 the module structure of the library at the moment and should be adapted in case larger refactorings take place. This makes it easy for developers already familiar with the project structure to also contribute to the documentation if further explanation is needed.

The goal of this PR is to lay the foundation for further exhaustive documentation of each code component (ref. #318, #90, #35), as well as improving docstring quality and guiding future refactors leading py-libp2p to a state where we can remove the WIP label from it. 🙂

dmuhs · 2019-10-23T16:50:35Z

Added fix for mypy error, taken from d52b093

mhchia

Awesome! I tried and it works well. However, I'm not familiar with the docs setup. It will be great to have @carver 's review, regarding #294.

pipermerriam · 2019-10-24T18:24:09Z

cc @cburgdorf who is our resident documentation expert.

carver · 2019-10-25T00:33:28Z

For reference, here's an excerpt of the global makefile we use to build docs in Trinity: https://github.com/ethereum/trinity/blob/24213d8f22a03c370313d3a990eea6a2fe1e76e4/Makefile#L43-L57

I'm happy to take a look at this PR tomorrow.

carver

Now that I look deeper, I'm seeing a bunch of things that I would like to see added, like towncrier support for release notes. If you'd like, I can pick it up from here and add more of these things.

carver · 2019-10-25T21:46:22Z

libp2p/stream_muxer/mplex/mplex_stream.py

@@ -146,7 +146,7 @@ def is_initiator(self) -> bool:
        :return: number of bytes written
        """
        if self.event_local_closed.is_set():
-            raise MplexStreamClosed(f"cannot write to closed stream: data={data}")
+            raise MplexStreamClosed(f"cannot write to closed stream: data={data!r}")


I'd recommend this one to be moved to another PR, it should be a very quick 👍

It seems like this is already resolved in master with d52b093. I have merged it into my PR branch and the changes are resolved correctly.

carver · 2019-10-25T21:47:44Z

libp2p/utils.py

@@ -77,7 +77,7 @@ def encode_delim(msg: bytes) -> bytes:
        raise ParseError(f"`len(msg_bytes)` should not be 0")
    if msg_bytes[-1:] != b"\n":
        raise ParseError(
-            f'`msg_bytes` is not delimited by b"\\n": `msg_bytes`={msg_bytes}'
+            f'`msg_bytes` is not delimited by b"\\n": `msg_bytes`={msg_bytes!r}'


This one can also be added to that separate PR.

Also fixed in d52b093 on master already

carver · 2019-10-25T21:55:12Z

setup.py

@@ -16,7 +16,7 @@
        "isort==4.3.21",
        "flake8>=3.7.7,<4.0.0",
    ],
-    "dev": ["tox>=3.13.2,<4.0.0"],
+    "dev": ["tox>=3.13.2,<4.0.0", "Sphinx>=2.2.0,<3.0.0", "sphinx-rtd-theme"],


It can be nice to move this to its own doc extra, like:

https://github.com/ethereum/trinity/blob/0ef04653c17d726463ae8a7f0ac01e0dcd930d54/setup.py#L85-L91

Fixed in f7403ef and added doc dependencies to the dev requirements in 817e9c8

cburgdorf · 2019-10-28T08:22:07Z

docs/source/index.rst

@@ -0,0 +1,17 @@
+Welcome to py-libp2p's documentation!


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

cburgdorf · 2019-10-28T08:26:53Z

docs/source/installation.rst

+Stable release
+--------------
+
+To install :code:`py-libp2p`:, run this command in your terminal:


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

pacrob · 2024-04-20T14:39:06Z

Docs reorged and more in #454

dmuhs added 5 commits October 21, 2019 15:30

Add basic autodoc and doc file structure

7442d3f

Fix formatting in docs conf

3621f0b

Fix unexpected indentation warning in Swarm.listen docstring

fc65511

Add installation notes

78aa5f9

Fix mypy errors

3d13153

dmuhs force-pushed the master branch from b5dc89e to 3d13153 Compare October 23, 2019 16:42

mhchia approved these changes Oct 24, 2019

View reviewed changes

carver reviewed Oct 25, 2019

View reviewed changes

dmuhs added 3 commits October 26, 2019 12:51

Add setup.py doc extra

f7403ef

Merge branch 'master' of github.com:libp2p/py-libp2p

d4808a6

Add docs to extra dev requirements

817e9c8

dmuhs requested review from carver October 26, 2019 11:26

cburgdorf reviewed Oct 28, 2019

View reviewed changes

ntninja mentioned this pull request Feb 19, 2020

Next Steps ipfs-shipyard/py-ipfs#49

Open

16 tasks

pacrob mentioned this pull request Mar 23, 2024

Docs cleanup - framework for filling in later #451

Merged

2 tasks

pacrob closed this Apr 20, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation #330

Add documentation #330

dmuhs commented Oct 23, 2019 •

edited

Loading

dmuhs commented Oct 23, 2019

mhchia left a comment •

edited

Loading

pipermerriam commented Oct 24, 2019

carver commented Oct 25, 2019

carver left a comment

carver Oct 25, 2019

dmuhs Oct 26, 2019 •

edited

Loading

carver Oct 25, 2019

dmuhs Oct 26, 2019

carver Oct 25, 2019

dmuhs Oct 26, 2019

cburgdorf Oct 28, 2019

cburgdorf Oct 28, 2019

pacrob commented Apr 20, 2024

Add documentation #330

Add documentation #330

Conversation

dmuhs commented Oct 23, 2019 • edited Loading

dmuhs commented Oct 23, 2019

mhchia left a comment • edited Loading

Choose a reason for hiding this comment

pipermerriam commented Oct 24, 2019

carver commented Oct 25, 2019

carver left a comment

Choose a reason for hiding this comment

carver Oct 25, 2019

Choose a reason for hiding this comment

dmuhs Oct 26, 2019 • edited Loading

Choose a reason for hiding this comment

carver Oct 25, 2019

Choose a reason for hiding this comment

dmuhs Oct 26, 2019

Choose a reason for hiding this comment

carver Oct 25, 2019

Choose a reason for hiding this comment

dmuhs Oct 26, 2019

Choose a reason for hiding this comment

cburgdorf Oct 28, 2019

Choose a reason for hiding this comment

General

Fundamentals

Community

cburgdorf Oct 28, 2019

Choose a reason for hiding this comment

pacrob commented Apr 20, 2024

dmuhs commented Oct 23, 2019 •

edited

Loading

mhchia left a comment •

edited

Loading

dmuhs Oct 26, 2019 •

edited

Loading