Skip to content

Add docs README to explain testing procedure #205

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.

Sign up for GitHub

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

Merged
michaeldiamant merged 6 commits into from
Feb 24, 2022
Merged

Add docs README to explain testing procedure #205

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ef4b732
Add docs README to explain testing procedure
michaeldiamant Feb 23, 2022
e9b76c8
Link top-level README to docs README
michaeldiamant Feb 23, 2022
fdfbc10
Update README to use relative path to Github Actions
michaeldiamant Feb 23, 2022
e043d5e
Remove unused, deprecated m2r dependency
michaeldiamant Feb 24, 2022
d5fa081
Remove outdated verbiage about isolating docs virtualenv
michaeldiamant Feb 24, 2022
eb6da01
Update docs to remove inaccurate releasing info
michaeldiamant Feb 24, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,8 @@ If needed, it's possible to install directly from the latest commit on master to

### Documentation

[PyTeal Docs](https://pyteal.readthedocs.io/)
* [PyTeal Docs](https://pyteal.readthedocs.io/)
* `docs/` ([README](docs/README.md)) contains raw docs.

### Development Setup

Expand Down
20 changes: 20 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Docs

`docs/` contains end user documentation geared towards writing smart contracts with PyTeal. The README explains how to edit docs.

## Local testing

Pyteal uses [Sphinx](https://github.com/sphinx-doc/sphinx) to generate HTML from RST files. Test changes by generating HTML and viewing with a web browser.

Here's the process:
* Perform one-time environment setup:
* Activate the top-level virtual environment.
* Install dependencies: `pip install -r requirements.txt`.
* Generate HTML docs: `make html`.
* If successful, generated HTML is available in `docs/_build/html`.

Additionally, each PR commit generates HTML docs via [Github Actions](../.github/workflows/build.yml).

## Releasing

Production docs live at https://pyteal.readthedocs.io/en/stable/.
5 changes: 2 additions & 3 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,8 @@
# Add any Sphinx extension module names here, as strings. They can be
Copy link
Contributor Author

@michaeldiamant michaeldiamant Feb 24, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unrelated to the line, but opening a thread to isolate messaging.

While removing m2r, we observed multiple make html warnings and errors. I investigated to discover the branch behavior is no worse than master. While undesirable, since the behavior is no worse, I propose addressing the warnings and errors out-of-band to the PR.

Here's what I did:

  • Capture make html output from master and the branch: make html >>/tmp/make_html_pyteal_docs_readme.txt 2>&1.
  • Diff warnings and errors. The output shows the branch produces 2 fewer warnings and the same errors.
(.venv) michael@albode docs % diff <(grep -iE 'warning|error' /tmp/make_html_master.txt) <(grep -iE 'warning|error' /tmp/make_html_pyteal_docs_readme.txt)
1d0
< WARNING: html_static_path entry '_static' does not exist
14d12
< /Users/michael/dev/pyteal/docs/.venv/lib/python3.10/site-packages/idna-3.3.dist-info/LICENSE.md: WARNING: document isn't included in any toctree
22c20
< build succeeded, 21 warnings.
---
> build succeeded, 19 warnings.

# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
# extensions = ['m2r']
extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
source_suffix = [".rst", ".md"]
source_suffix = [".rst"]
master_doc = "index"

napoleon_include_init_with_doc = True
Expand All @@ -54,4 +53,4 @@
# 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"]
# html_static_path = ["_static"]
Copy link
Contributor Author

@michaeldiamant michaeldiamant Feb 24, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For reviewers: I commented out the highlighted line because it seems we're not making use of the _static path. With the change, the following warning no longer occurs on make html:

WARNING: html_static_path entry '_static' does not exist

If there's a reason to keep the configuration, let me know and I'll revert.

1 change: 0 additions & 1 deletion docs/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,2 @@
m2r
Copy link
Contributor Author

@michaeldiamant michaeldiamant Feb 24, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Leaving a trail in case someone comes back to the PR later.

We opted to remove m2r because the dependency does not install with Python 3.10. Here's the error:

  Using cached m2r-0.1.0.tar.gz (10 kB)
    ERROR: Command errored out with exit status 1:
     command: /Users/michael/dev/pyteal/.venv/bin/python3 -c 'import io, os, sys, setuptools, tokenize; sys.argv[0] = '"'"'/private/var/folders/m6/4mf0p_y17yn_sx2gt7fpcj980000gp/T/pip-install-s36zhju9/m2r_0fbb41fce6504a278f0ec41cd3a97e49/setup.py'"'"'; __file__='"'"'/private/var/folders/m6/4mf0p_y17yn_sx2gt7fpcj980000gp/T/pip-install-s36zhju9/m2r_0fbb41fce6504a278f0ec41cd3a97e49/setup.py'"'"';f = getattr(tokenize, '"'"'open'"'"', open)(__file__) if os.path.exists(__file__) else io.StringIO('"'"'from setuptools import setup; setup()'"'"');code = f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base /private/var/folders/m6/4mf0p_y17yn_sx2gt7fpcj980000gp/T/pip-pip-egg-info-sgk4t6mj
         cwd: /private/var/folders/m6/4mf0p_y17yn_sx2gt7fpcj980000gp/T/pip-install-s36zhju9/m2r_0fbb41fce6504a278f0ec41cd3a97e49/
    Complete output (7 lines):
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/private/var/folders/m6/4mf0p_y17yn_sx2gt7fpcj980000gp/T/pip-install-s36zhju9/m2r_0fbb41fce6504a278f0ec41cd3a97e49/setup.py", line 13, in <module>
        from m2r import parse_from_file
      File "/private/var/folders/m6/4mf0p_y17yn_sx2gt7fpcj980000gp/T/pip-install-s36zhju9/m2r_0fbb41fce6504a278f0ec41cd3a97e49/m2r.py", line 22, in <module>
        class RestBlockGrammar(mistune.BlockGrammar):
    AttributeError: module 'mistune' has no attribute 'BlockGrammar'

Additionally, the dependency is deprecated and replaced by m2r2. We confirmed the replacement dependency works with docs/, but opted to remove it because it's unused.

sphinx_rtd_theme
py-algorand-sdk