Skip to content
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

Jump to bottom

docs: update python docs template #576

Merged
merged 3 commits into from
May 28, 2020
Merged

docs: update python docs template #576

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
aa5553c
docs: update python docs template
kolea2 May 21, 2020
5f58e29
sphinx change
kolea2 May 21, 2020
d30fdb4
Merge branch 'master' into python-update-doc-config
kolea2 May 26, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
5 changes: 1 addition & 4 deletions synthtool/gcp/templates/python_library/docs/conf.py.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ extensions = [
"sphinx.ext.napoleon",
"sphinx.ext.todo",
"sphinx.ext.viewcode",
"recommonmark",
Copy link
Member

Choose a reason for hiding this comment

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

We did the same change in python-storage: googleapis/python-storage#103

Didn't realize it came from this parent template. The rationale for it:

https://github.com/readthedocs/recommonmark

# for Sphinx-1.4 or newer
extensions = ['recommonmark'] # <---- this 

# for Sphinx-1.3
from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

]

# autodoc/autosummary flags
Expand All @@ -49,10 +50,6 @@ autosummary_generate = True
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

# Allow markdown includes (so releases.md can include CHANGLEOG.md)
# http://www.sphinx-doc.org/en/master/markdown.html
source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
Expand Down
2 changes: 1 addition & 1 deletion synthtool/gcp/templates/python_library/noxfile.py.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,7 @@ def docs(session):
"""Build the docs for this library."""

session.install('-e', '.')
session.install('sphinx<3.0.0', 'alabaster', 'recommonmark')
session.install('sphinx', 'alabaster', 'recommonmark')
Copy link
Contributor

Choose a reason for hiding this comment

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

@crwilcox IIRC, you needed a specific version of sphinx. Will this break you?

Copy link
Collaborator Author

@kolea2 kolea2 May 21, 2020 •
edited

Choose a reason for hiding this comment

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

We made this change here: googleapis/python-bigtable#20 and the docs build passed successfully, so we wanted to make this change more broadly.

Copy link
Contributor

Choose a reason for hiding this comment

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

@kolea2 is correct. A contributor made this change to bigtable specifically. And it seems @frankyn has had the same experience for storage specifically. This change undoes a mitigation while we were incompatible with newer versions of sphinx.


shutil.rmtree(os.path.join('docs', '_build'), ignore_errors=True)
session.run(
Expand Down