Modal with instructions to "Add project" workflow

[humitos]

We talked about adding a modal with more detailed step by step instructions.

• Add project: change copy for "Finish" button #434

I understand we want to have a new button "I need help" or similar that shows this modal. Besides, this could also be integrated in the future with an automatic check for .readthedocs.yaml in the repository that grays out the "This file exists" (or similar) when we don't find this file.

Front conversations

[humitos]

automatic check for .readthedocs.yaml in the repository

I took a quick look at this and it seems we have to clone the repository to check this. We could use the GitHub API for this, but it would only works for GitHub projects -- not all Git repositories. Maybe is a good first step, tho.

https://docs.github.com/en/rest/repos/contents?apiVersion=2022-11-28#get-repository-content

Using that endpoint we could check for 200 and/404 HTTP status codes.

File found

$ curl https://api.github.com/repos/readthedocs/readthedocs.org/contents/.readthedocs.yml
{
  "name": ".readthedocs.yml",
  "path": ".readthedocs.yml",
  "sha": "ac2c56f6d29018a64ca2506b3ca434ea0eddf58c",
  "size": 1560,
  "url": "https://api.github.com/repos/readthedocs/readthedocs.org/contents/.readthedocs.yml?ref=main",
  "html_url": "https://github.com/readthedocs/readthedocs.org/blob/main/.readthedocs.yml",
  "git_url": "https://api.github.com/repos/readthedocs/readthedocs.org/git/blobs/ac2c56f6d29018a64ca2506b3ca434ea0eddf58c",
  "download_url": "https://raw.githubusercontent.com/readthedocs/readthedocs.org/main/.readthedocs.yml",
  "type": "file",
  "content": "dmVyc2lvbjogMgoKZm9ybWF0czoKICAtIGVwdWIKICAtIGh0bWx6aXAKCnNw\naGlueDoKICBjb25maWd1cmF0aW9uOiBkb2NzL2NvbmYucHkKCiAgIyBEaXNh\nYmxlZCBkdWUgdG8gdGVtcG9yYXJ5IGlzc3VlIHdpdGggRGphbmdvIGRvY3MK\nICBmYWlsX29uX3dhcm5pbmc6IGZhbHNlCgpweXRob246CiAgaW5zdGFsbDoK\nICAgIC0gcmVxdWlyZW1lbnRzOiByZXF1aXJlbWVudHMvZG9jcy50eHQKCmJ1\naWxkOgogIG9zOiB1YnVudHUtMjIuMDQKICB0b29sczoKICAgIHB5dGhvbjog\nIjMuMTAiCiAgam9iczoKICAgIHBvc3RfY2hlY2tvdXQ6CiAgICAgICMgaHR0\ncHM6Ly9kb2NzLnJlYWR0aGVkb2NzLmlvL2VuL3N0YWJsZS9idWlsZC1jdXN0\nb21pemF0aW9uLmh0bWwjY2FuY2VsLWJ1aWxkLWJhc2VkLW9uLWEtY29uZGl0\naW9uCiAgICAgICMKICAgICAgIyBDYW5jZWwgYnVpbGRpbmcgcHVsbCByZXF1\nZXN0cyB3aGVuIHRoZXJlIGFyZW4ndCBjaGFuZ2VkIGluIHRoZSBkb2NzIGRp\ncmVjdG9yeS4KICAgICAgIwogICAgICAjIElmIHRoZXJlIGFyZSBubyBjaGFu\nZ2VzIChnaXQgZGlmZiBleGl0cyB3aXRoIDApIHdlIGZvcmNlIHRoZSBjb21t\nYW5kIHRvIHJldHVybiB3aXRoIDE4My4KICAgICAgIyBUaGlzIGlzIGEgc3Bl\nY2lhbCBleGl0IGNvZGUgb24gUmVhZCB0aGUgRG9jcyB0aGF0IHdpbGwgY2Fu\nY2VsIHRoZSBidWlsZCBpbW1lZGlhdGVseS4KICAgICAgLSB8CiAgICAgICAg\naWYgWyAiJFJFQURUSEVET0NTX1ZFUlNJT05fVFlQRSIgPSAiZXh0ZXJuYWwi\nIF0gJiYgZ2l0IGRpZmYgLS1xdWlldCBvcmlnaW4vbWFpbiAtLSBkb2NzLyAu\ncmVhZHRoZWRvY3MueW1sIHJlcXVpcmVtZW50cy9kb2NzLnR4dDsKICAgICAg\nICB0aGVuCiAgICAgICAgICBlY2hvICJObyBjaGFuZ2VzIHRvIGRvY3MvIC0g\nZXhpdGluZyB0aGUgYnVpbGQuIjsKICAgICAgICAgIGV4aXQgMTgzOwogICAg\nICAgIGZpCgpzZWFyY2g6CiAgcmFua2luZzoKICAgICMgRGVwcmVjYXRlZCBj\nb250ZW50CiAgICBhcGkvdjEuaHRtbDogLTEKICAgIGNvbmZpZy1maWxlL3Yx\nLmh0bWw6IC01CgogICAgIyBTdXJmYWNlIHRoZSB0dXRvcmlhbCBjb250ZW50\nIGZpcnN0LCB0aGlzIHBhZ2UgY292ZXJzIHRoZSBjb25maWd1cmF0aW9uCiAg\nICAjIGZpbGUgYmFzaWNzIHZlcnkgd2VsbC4gVGhlIGV4cGxhbmF0aW9uIHBh\nZ2UgaXMgbW9yZSBjb25jZXB0dWFsIGFuZCBhYm91dAogICAgIyB2ZXJzaW9u\naW5nLiBCdW1wIHVwIHRoZSB2MiByZWZlcmVuY2UgcGFnZSBhIGxpdHRsZSB0\nb28sIGJ1dCB0aGUgdHV0b3JpYWwKICAgICMgc2hvdWxkIGJlIHRoZSBmaXJz\ndCBwYWdlIHRoZSB1c2VyIGxvb2tzIGF0IHN0aWxsLgogICAgY29uZmlnLWZp\nbGUvaW5kZXguaHRtbDogNQogICAgY29uZmlnLWZpbGUvdjIuaHRtbDogMgog\nICAgZXhwbGFuYXRpb24vY29uZmlndXJhdGlvbi1maWxlLmh0bWw6IC0xCgog\nICAgIyBVc2VmdWwgY29udGVudCwgYnV0IG5vdCBzb21ldGhpbmcgd2Ugd2Fu\ndCBtb3N0IHVzZXJzIGZpbmRpbmcKICAgIGNoYW5nZWxvZy5odG1sOiAtNgog\nIGlnbm9yZToKICAgIC0gZG1jYS9hcmNoaXZlLyoK\n",
  "encoding": "base64",
  "_links": {
    "self": "https://api.github.com/repos/readthedocs/readthedocs.org/contents/.readthedocs.yml?ref=main",
    "git": "https://api.github.com/repos/readthedocs/readthedocs.org/git/blobs/ac2c56f6d29018a64ca2506b3ca434ea0eddf58c",
    "html": "https://github.com/readthedocs/readthedocs.org/blob/main/.readthedocs.yml"
  }
}

File not found

$ curl https://api.github.com/repos/readthedocs/readthedocs.org/contents/invalid-filename.rst
{
  "message": "Not Found",
  "documentation_url": "https://docs.github.com/rest/repos/contents#get-repository-content",
  "status": "404"
}

[ericholscher]

Yea, I think starting with just GitHub (and GitLab if they have a similar API) is very reasonable. They are ~90% of our users, and allow us to provide a good experience.

[agjohnson]

I think there are still two projects here. I would start with the UI changes in this issue, and do the work on automated checks afterwards. We'll want the UI and UX to be generically usable, so it makes sense in the context of GitHub users automatically checking their repository and also everyone else doing manual checks for the file -- GitLab/etc users, manual creation users, etc.

The automated part doesn't need to happen in order to build this UX, but it does help to anticipate how this UX will eventually affect this UI.