Create user facing documentation structure

[ewdurbin]

Uses mkdocs for building https://docs.pypi.org/

This will serve as the location for user-facing documentation moving forward. We should begin separating developer docs from the /docs directory, and @s-mm will be adding documentation for organization accounts here.

[dstufft]

Question that's maybe already been discussed, should we use packaging.python.org for PyPI's docs so that people have less places to go to look for Python packaging documentation? Or do we think that PyPI has docs that should be distinct from the overall packaging docs?

I'm OK either way, just figured I'd raise the question!

[ewdurbin]

We'll have some very PyPI specific docs relating to Organizations and any other paid-features down the line. That's the main driver for this docset.

[di]

Or do we think that PyPI has docs that should be distinct from the overall packaging docs?

IMO, docs like https://packaging.python.org/en/latest/guides/analyzing-pypi-package-downloads/ are already somewhat out of place on p.p.o, but docs about PyPI-specific features would be even more out of place.

Additionally, I think there's an advantage to keeping docs alongside the code in one repo, as it makes it easier to keep them accurate and up to date.

[dstufft]

👍

[ewdurbin]

this is semi-blocked on readthedocs/readthedocs.org#8234.

as is there is no clean way to host multiple RTD projects out of a single repo/branch.

[humitos]

I arrived at this issue while reading your comment and PR on Read the Docs.

this is semi-blocked on readthedocs/readthedocs.org#8234.

as is there is no clean way to host multiple RTD projects out of a single repo/branch.

I noted from the description that you are using MkDocs, so I'm not sure if it's currently possible to do this. However, the official Read the Docs user and developer documentation use a Sphinx extension to allow us this use case:

• https://dev.readthedocs.io/
• https://docs.readthedocs.io/

The Sphinx extension is https://github.com/readthedocs/sphinx-multiproject/

I don't think this will solve your problem, but maybe gives you an idea for a potential workaround and unblock you. I hope it helps 😄

Edit: this issue on Read the Docs looks related as well readthedocs/readthedocs.org#8811

[humitos]

Another potential immediate solution for this could be using build.commands (https://docs.readthedocs.io/en/latest/build-customization.html) and decide what commands execute depending on the project's slug (READTHEDOCS_PROJECT environment variable)

# .readthedocs.yaml
version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3"
  commands:
    - |
        if [ "$READTHEDOCS_PROJECT" = "developer" ] ;
        then
          cd docs/developer;
          mkdocs build;
          mv _build/html ../_readthedocs/html;
        fi
  - |
      if [ "$READTHEDOCS_PROJECT" = "user" ] ;
        then
          cd docs/user;
          mkdocs build;
          mv _build/html ../_readthedocs/html;
        fi

I grabbed this idea from readthedocs/readthedocs.org#8811 (comment). Let me know that could work for now.

[humitos]

He, I just saw that you are fighting with the shell in YAML. I've been there as well, and it was frustrating 😞 . Maybe you can follow this example from our docs that it's working already. It's hard to tell you what are the syntax issues you are having in yours, tho; https://github.com/readthedocs/readthedocs.org/blob/main/.readthedocs.yml#L26

[ewdurbin]

yeah, struggling indeed! getting confused since running these in a true /bin/sh on ubuntu-22.04 works 😅

[ewdurbin]

@humitos given that 50f591b failed and 8e06fdc worked... it seems there is something different in the handling of shell commands in build.jobs versus build.commands

[humitos]

🤯 -- I have no idea what could be happening. It looks weird to me at simple sight. In theory, there shouldn't be any differences.

• code for build.jobs: https://github.com/readthedocs/readthedocs.org/blob/f4215c5516eaa07c15afe49abdf1bb7a1a34655a/readthedocs/doc_builder/director.py#L292-L333
• code for build.commands: https://github.com/readthedocs/readthedocs.org/blob/f4215c5516eaa07c15afe49abdf1bb7a1a34655a/readthedocs/doc_builder/director.py#L335-L370

I'm closing my day now because I'm super tired, but I'll jump into this tomorrow's morning with fresh eyes. Hopefully, I can give you a better answer.

[ewdurbin]

8a79c92 indicates that its a difference in the environments that the commands are run.

post_checkout is the only job run in the vcs_environment, all subsequent jobs are run in the build_enviornment just like build.command.

[ewdurbin]

I'm going to remove the deployment portion of this and merge so @s-mm can begin opening PRs against the user-docs directory for organization documentation.

When read the docs supports our use case, we will revisit deployment.

[humitos]

@ewdurbin today I opened a PR that I think it will solve the issue you are having with the script syntax error: readthedocs/readthedocs.org#10119. It's under review now, but it has high changes to get deployed next Tuesday 🙏🏼

[ewdurbin]

thanks @humitos, is there any way we'll know when it deploys other than tryin' it out?

[humitos]

@ewdurbin it's already merged -- It's going to be deployed next Tuesday at 5PM CET

[ewdurbin]

@ewdurbin it's already merged -- It's going to be deployed next Tuesday at 5PM CET

Nice! I'll get a follow-up PR for this one ready after it is merged. :) Thank you!

[di]

@ewdurbin Are you OK with this change to the directory structure here? I think this will make it a little more clean/organized, especially when we add another docsite: docs_pypi_org...docs_pypi_org-patch

[ewdurbin]

absolutely, send it!

[di]

@ewdurbin This should be good to merge.

[ewdurbin]

Thank you for the tidying!