Skip to content

Normalize nox / docs builds #636

@tseaver

Description

@tseaver

docgen

noxfile.pycontains adocgensession which, when run, delete's / overwrites some files in thedocs/reference` tree:

$ nox -re docgen
nox > Running session docgen
nox > Re-using existing virtual environment at .nox/docgen.
nox > pip install flask freezegun mock oauth2client pyopenssl pytest pytest-cov pytest-localserver requests urllib3 cryptography responses grpcio
nox > pip install sphinx
nox > pip install .
nox > rm -r docs/reference
nox > Warning: rm is not installed into the virtualenv, it is located at /bin/rm. This might cause issues! Pass external=True into run() to silence this message.
nox > sphinx-apidoc --output-dir docs/reference --separate --module-first google
Creating file docs/reference/google.rst.
Creating file docs/reference/google.auth.rst.
Creating file docs/reference/google.auth.app_engine.rst.
Creating file docs/reference/google.auth.credentials.rst.
Creating file docs/reference/google.auth.environment_vars.rst.
Creating file docs/reference/google.auth.exceptions.rst.
Creating file docs/reference/google.auth.iam.rst.
Creating file docs/reference/google.auth.impersonated_credentials.rst.
Creating file docs/reference/google.auth.jwt.rst.
Creating file docs/reference/google.auth.compute_engine.rst.
Creating file docs/reference/google.auth.compute_engine.credentials.rst.
Creating file docs/reference/google.auth.crypt.rst.
Creating file docs/reference/google.auth.crypt.base.rst.
Creating file docs/reference/google.auth.crypt.es256.rst.
Creating file docs/reference/google.auth.crypt.rsa.rst.
Creating file docs/reference/google.auth.transport.rst.
Creating file docs/reference/google.auth.transport.grpc.rst.
Creating file docs/reference/google.auth.transport.mtls.rst.
Creating file docs/reference/google.auth.transport.requests.rst.
Creating file docs/reference/google.auth.transport.urllib3.rst.
Creating file docs/reference/google.oauth2.rst.
Creating file docs/reference/google.oauth2.credentials.rst.
Creating file docs/reference/google.oauth2.id_token.rst.
Creating file docs/reference/google.oauth2.service_account.rst.
Creating file docs/reference/modules.rst.
nox > Session docgen was successful.
[/home/tseaver/projects/agendaless/Google/src/google-auth] 
$ git stat
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	deleted:    docs/reference/google.auth.credentials_async.rst
	deleted:    docs/reference/google.auth.jwt_async.rst
	modified:   docs/reference/google.auth.rst
	deleted:    docs/reference/google.auth.transport.aiohttp_requests.rst
	modified:   docs/reference/google.auth.transport.rst
	deleted:    docs/reference/google.oauth2.credentials_async.rst
	modified:   docs/reference/google.oauth2.rst
	deleted:    docs/reference/google.oauth2.service_account_async.rst

I recommend that we delete this section, as a fossil of an approach we no longer mean to support.

docs session

The docs session triggers the build via make (and the docs/Makefile), rather than running sphinx-build directly as in other projects. This choice is unique across all our projects, and means that we don't enforce
the same specs here (e.g., Sphinx warnings are not treated as errors).

I recommend we delete the docs/Makefile and normalize the docs session, fixing any Sphinx warnings found.

Metadata

Metadata

Assignees

No one assigned

    Labels

    type: processA process-related concern. May include testing, release, or the like.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions