Suggest twine-check

[sgillies]

To diagnose description render failures.

This is my first contribution to the help page. I hope I understand the structure correctly.

[ewdurbin]

We should be linking to the #description_content_type anchor when errors occur rendering, so perhaps we should add this sentence to that help text.

[sgillies]

@ewdurbin thanks for the suggestion, I'll add more detail. Does the help page get rendered to RTD or a staging site where I can see the changes? Or do I need to run a local warehouse to observe the results?

[ewdurbin]

That page is rendered via this codebase, so you will need to run warehouse locally.

[sgillies]

I'm having trouble getting started with make build. Might be related to #10447.

seangillies@PF3675VY:~/projects/warehouse$ make build
make[1]: Circular requirements/docs.txt <- .state/env/pyvenv.cfg dependency dropped.
make[1]: Circular requirements/lint.txt <- .state/env/pyvenv.cfg dependency dropped.
ERROR:pip.subprocessor:[present-diagnostic] python setup.py egg_info exited with 1
Traceback (most recent call last):
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/pip/_internal/operations/build/metadata_legacy.py", line 64, in generate_metadata
    call_subprocess(
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/pip/_internal/utils/subprocess.py", line 224, in call_subprocess
    raise error
pip._internal.exceptions.InstallationSubprocessError: python setup.py egg_info exited with 1

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/seangillies/projects/warehouse/.state/env/bin/pip-compile", line 8, in <module>
    sys.exit(cli())
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/click/core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/click/core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/click/core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/click/core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/click/decorators.py", line 26, in new_func
    return f(get_current_context(), *args, **kwargs)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/piptools/scripts/compile.py", line 466, in cli
    results = resolver.resolve(max_rounds=max_rounds)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/piptools/resolver.py", line 175, in resolve
    has_changed, best_matches = self._resolve_one_round()
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/piptools/resolver.py", line 319, in _resolve_one_round
    their_constraints.extend(self._iter_dependencies(best_match))
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/piptools/resolver.py", line 428, in _iter_dependencies
    dependencies = self.repository.get_dependencies(ireq)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/piptools/repositories/local.py", line 79, in get_dependencies
    return self.repository.get_dependencies(ireq)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/piptools/repositories/pypi.py", line 238, in get_dependencies
    self._dependencies_cache[ireq] = self.resolve_reqs(
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/piptools/repositories/pypi.py", line 201, in resolve_reqs
    results = resolver._resolve_one(reqset, ireq)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/pip/_internal/resolution/legacy/resolver.py", line 379, in _resolve_one
    dist = self._get_dist_for(req_to_install)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/pip/_internal/resolution/legacy/resolver.py", line 332, in _get_dist_for
    dist = self.preparer.prepare_linked_requirement(req)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/pip/_internal/operations/prepare.py", line 487, in prepare_linked_requirement
    return self._prepare_linked_requirement(req, parallel_builds)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/pip/_internal/operations/prepare.py", line 556, in _prepare_linked_requirement
    dist = _get_prepared_distribution(
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/pip/_internal/operations/prepare.py", line 58, in _get_prepared_distribution
    abstract_dist.prepare_distribution_metadata(finder, build_isolation)
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/pip/_internal/distributions/sdist.py", line 47, in prepare_distribution_metadata
    self.req.prepare_metadata()
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/pip/_internal/req/req_install.py", line 528, in prepare_metadata
    self.metadata_directory = generate_metadata_legacy(
  File "/home/seangillies/projects/warehouse/.state/env/lib/python3.8/site-packages/pip/_internal/operations/build/metadata_legacy.py", line 71, in generate_metadata
    raise MetadataGenerationFailed(package_details=details) from error
pip._internal.exceptions.MetadataGenerationFailed: metadata generation failed
make[1]: *** [Makefile:131: requirements/main.txt] Error 1
make: *** [Makefile:76: build] Error 2

[di]

I think this is due to psyscopg2 requiring platform-level dependencies to be installed in advance before it can be installed (see https://www.psycopg.org/docs/install.html). What platform are you on?

[sgillies]

@di I'm on Ubuntu 20.04 and was lacking libpq-dev. After installing that, a new make build completed. I'll add a note to the getting started doc about this. Or maybe we could find a way to install libpq-dev only in the image?

[di]

I think that's a good short-term fix until we can fix #4948.

[sgillies]

I've got a local warehouse running and have some screenshots of the changes in my patch-1 branch.

Here is the "Troubleshooting" tables of contents. Does the warehouse project have a convention for ordering of FAQ items? I've recently advocated for putting newest items on top and periodically checking the ones at the bottom for relevance and correctness, and have done that here. I'm happy to move it, though.

Here is the head of the troubleshooting section:

And here is the "different format" item:

As noted in f1b66c5, I moved some content from this section and left a pointer. Does that look okay?

[di]

I've recently advocated for putting newest items on top and periodically checking the ones at the bottom for relevance and correctness, and have done that here.

There's no ordering, I like this though!

[sgillies]

Okay, I believe this is ready for review. Thanks for the twine check tip on Twitter, last week @di!

The note I added can be seen at the end of the https://warehouse--10776.org.readthedocs.build/development/getting-started.html#building-the-warehouse-container section.