Migrate Continuous Documentation from Vercel to Readthedocs #1859

weiji14 · 2022-03-31T21:19:57Z

Description of proposed changes

PyGMT has been using Vercel (previously Zeit Now) since 2019, and that's been a great tool in checking out documentation previews on individual Pull Requests (PRs). However, the legacy service plan we're on will be deprecated on 12 May 2022, see https://vercel.com/support/articles/legacy-plans-deprecation

This Pull Request migrates the configuration to ReadtheDocs which is another web hosting platform. Note that this will only affect the redendered documentation previews for PRs. The documentation built on the main branch is still built and deployed using GitHub Actions.

I've set up the new URL to point to https://pygmt-devs.readthedocs.io. @GenericMappingTools/pygmt-maintainers, for those of you who would like access to the readthedocs backend, please register for an account on https://readthedocs.org/accounts/signup, and ping me so that I can add you to the maintainer list.

Cc @meghanrjones @seisman, I might need help setting up the readthedocs webhooks integration on the pygmt repo (ref https://docs.readthedocs.io/en/stable/integrations.html)

References:

Supersedes #344

Reminders

Run make format and make check to make sure the code follows the style guide.
Add tests for new features or tests that would have caught the bug that you're fixing.
Add new public functions/methods/classes to doc/api/index.rst.
Write detailed docstrings for all functions/methods.
If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

/format: automatically format and lint the code
/test-gmt-dev: run full tests on the latest GMT development version

Docs build uses mamba to install dependencies from environment.yml. See also https://docs.readthedocs.io/en/stable/config-file/v2.html and https://docs.readthedocs.io/en/stable/guides/conda.html

vercel · 2022-03-31T21:20:00Z

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/gmt/pygmt/GMATHSZtsYyH4oV2uCrzxwMs9Uxh
✅ Preview: https://pygmt-git-verceltoreadthedocs-gmt.vercel.app

seisman · 2022-04-01T04:12:10Z

Cc @meghanrjones @seisman, I might need help setting up the readthedocs webhooks integration on the pygmt repo (ref docs.readthedocs.io/en/stable/integrations.html)

Approved.

seisman · 2022-04-01T04:23:05Z

This Pull Request migrates the configuration to Read_the_Docs which is another web hosting platform. Note that this will only affect the redendered documentation previews for PRs. The documentation built on the main branch is still built and deployed using GitHub Actions. I've set up the new URL to point to pygmt-devs.readthedocs.io.

My concern is, we will have two domains that host the exact same contents, which may affect the SEO of of main site.

weiji14 · 2022-04-03T15:33:23Z

This Pull Request migrates the configuration to Read_the_Docs which is another web hosting platform. Note that this will only affect the redendered documentation previews for PRs. The documentation built on the main branch is still built and deployed using GitHub Actions. I've set up the new URL to point to pygmt-devs.readthedocs.io.

My concern is, we will have two domains that host the exact same contents, which may affect the SEO of of main site.

I've set the canonical URL to point to https://pygmt.org following https://docs.readthedocs.io/en/stable/custom_domains.html#canonical-urls. I think that should ensure that search engines point to the existing .org site?

seisman · 2022-04-03T15:52:49Z

This Pull Request migrates the configuration to Read_the_Docs which is another web hosting platform. Note that this will only affect the redendered documentation previews for PRs. The documentation built on the main branch is still built and deployed using GitHub Actions. I've set up the new URL to point to pygmt-devs.readthedocs.io.

My concern is, we will have two domains that host the exact same contents, which may affect the SEO of of main site.

I've set the canonical URL to point to pygmt.org following docs.readthedocs.io/en/stable/custom_domains.html#canonical-urls. I think that should ensure that search engines point to the existing .org site?

Looks great.

To fix `ModuleNotFoundError: No module named 'pygmt'`.

weiji14 · 2022-04-03T16:39:03Z

This Pull Request migrates the configuration to Read_the_Docs which is another web hosting platform. Note that this will only affect the redendered documentation previews for PRs. The documentation built on the main branch is still built and deployed using GitHub Actions. I've set up the new URL to point to pygmt-devs.readthedocs.io.

My concern is, we will have two domains that host the exact same contents, which may affect the SEO of of main site.

I've set the canonical URL to point to pygmt.org following docs.readthedocs.io/en/stable/custom_domains.html#canonical-urls. I think that should ensure that search engines point to the existing .org site?

Looks great.

Hmm, we might need to modify the pygmt.org DNS record somehow... Now the readthedocs preview documentation link points to http://pygmt.org/en/vercel_to_readthedocs 😅

weiji14 · 2022-06-10T20:38:23Z

I'm going to be flat out busy for the next month (travel, workshops, etc), so I probably won't have time to finish this up. @GenericMappingTools/pygmt-maintainers can someone maybe take over this Vercel to Readthedocs migration PR since Vercel is expiring soon? If you sign up for a readthedocs account at https://readthedocs.org/accounts/login/, I can add you to the pygmt-dev maintainer list at https://readthedocs.org/dashboard/pygmt-dev/users

seisman · 2022-06-11T02:31:20Z

Please add me as a maintainer so that I can give it a try.

weiji14 · 2022-06-11T04:03:19Z

Please add me as a maintainer so that I can give it a try.

Ok, done.

seisman · 2022-06-15T04:17:32Z

This Pull Request migrates the configuration to Read_the_Docs which is another web hosting platform. Note that this will only affect the redendered documentation previews for PRs. The documentation built on the main branch is still built and deployed using GitHub Actions. I've set up the new URL to point to pygmt-devs.readthedocs.io.

My concern is, we will have two domains that host the exact same contents, which may affect the SEO of of main site.

I've set the canonical URL to point to pygmt.org following docs.readthedocs.io/en/stable/custom_domains.html#canonical-urls. I think that should ensure that search engines point to the existing .org site?

Looks great.

Hmm, we might need to modify the pygmt.org DNS record somehow... Now the readthedocs preview documentation link points to http://pygmt.org/en/vercel_to_readthedocs 😅

I think you were NOT reading the right documentation when setting the canonical URLs. The correct documentation is here: https://docs.readthedocs.io/en/stable/canonical-urls.html. I've removed the settings of custom domains in the Admin panel.

vercel · 2022-06-15T04:18:00Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
pygmt	✅ Ready (Inspect)	Visit Preview	Jul 30, 2022 at 1:49AM (UTC)

…NIFEST.in

weiji14 · 2022-06-22T02:24:06Z

.readthedocs.yaml

+
+# Optionally declare the Python requirements required to build your docs
+conda:
+  environment: environment.yml


Do you think we should just install the sphinx-related libraries needed for building the docs? We used to install everything on Vercel because it's quite fast, but Readthedocs is a bit slower it seems, so less libraries might speed things up.

Refer to ci_docs.yml for dependencies needed:

pygmt/.github/workflows/ci_docs.yml

Lines 73 to 75 in 9802909

mamba install gmt=6.3.0 numpy pandas xarray netCDF4 packaging \

build ipython make myst-parser geopandas \

sphinx sphinx-copybutton sphinx-design sphinx-gallery sphinx_rtd_theme

Done in d21acf9.

Slightly faster. Now it takes 12 minutes.

seisman · 2022-06-23T01:38:19Z

.github/workflows/docs_environment.yml

@@ -0,0 +1,26 @@
+name: pygmt


Is .github/workflows a good place to save these environment files?

I believe we will also use it in ci_docs.yml.

inspiration from xarray - https://github.com/pydata/xarray/tree/main/ci/requirements

Sounds a good place to put all CI related files.

Ping @weiji14 for comments on this.

Ideally we would put all these 'docs' dependencies as an 'extras' in pyproject.toml/setup.py following https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies so that we could just pip install .[docs]. However, GMT would still need to come from conda-forge, unless #1853 becomes a thing 🙂

Actually, is the GMT C library needed to build the docs? Could we just mock it out? I recall @meghanrjones was able to use https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports at xarray-contrib/xbatcher#62 (comment), though not sure if it works in this case. If it does work though, then my comment at https://github.com/GenericMappingTools/pygmt/pull/1859/files#r904531125 about using 'extras' would be the way to go.

Actually, is the GMT C library needed to build the docs? Could we just mock it out?

I don't think it's possible. We need to call the GMT C library to generate images (i.e.., all the images generated by sphinx-gallery).

seisman · 2022-07-07T08:27:01Z

ci/requirements/docs.yml

+dependencies:
+    # Required dependencies
+    - pip
+    - gmt=6.3.0


Also need to update https://github.com/GenericMappingTools/pygmt/blob/main/.github/ISSUE_TEMPLATE/bump_gmt_checklist.md

Yeah, if we merge this PR first, will need to update bump_gmt_checklist.md directly in #1990 later.

maxrjones

LGTM, thanks! We should update the permissions for the vercel app after merging this.

weiji14 · 2022-07-31T14:10:35Z

Just wanted to say, thanks @maxrjones and @seisman for keeping things going! Sorry that I haven't been as active lately, it's been really intense with FDL2022 (even over weekends), and I'll probably be busy until mid-August at least. Hoping to get back up to speed on PyGMT contributions from September onwards after I catch up with a backlog of stuff!

LGTM, thanks! We should update the permissions for the vercel app after merging this.

I took at a look at the Vercel project dashboard for pygmt, and it should be disconnected already as far as I can tell (maybe someone already disconnected it in the GitHub org settings)? I didn't delete the PyGMT project on Vercel, so the old links vercel links in PRs should still work as long as they're still willing to host it. Will keep an eye out in case comments like d3b5fdc#commitcomment-79850583 still pop up.

seisman · 2022-07-31T15:02:21Z

I took at a look at the Vercel project dashboard for pygmt, and it should be disconnected already as far as I can tell (maybe someone already disconnected it in the GitHub org settings)?

Yes, I did it.

Will keep an eye out in case comments like d3b5fdc#commitcomment-79850583 still pop up.

I think the comment was made before I disconnected the Vercel service, so we should be good to go.

…appingTools#1859) * Remove vercel configuration files * Setup readthedocs configuration file * Run pip install . in the readthedocs build environment * Remove vercel configurations and add readthedocs configurations in MANIFEST.in * Update doc/maintenance.md to trigger builds in PR * Set canonical URL by setting html_baseurl * Update contributing and maintenance guides * Customize the pre_build step to generate API stub files * Only install packages required for building docs * Move the docs environment file to the ci directory Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

weiji14 added 2 commits March 31, 2022 16:45

Remove vercel configuration files

7123f22

Setup readthedocs configuration file

5b7a43c

Docs build uses mamba to install dependencies from environment.yml. See also https://docs.readthedocs.io/en/stable/config-file/v2.html and https://docs.readthedocs.io/en/stable/guides/conda.html

weiji14 added the maintenance Boring but important stuff for the core devs label Mar 31, 2022

weiji14 added this to the 0.6.1 milestone Mar 31, 2022

weiji14 self-assigned this Mar 31, 2022

weiji14 added 2 commits April 3, 2022 12:15

Merge branch 'main' into vercel_to_readthedocs

23507e3

Run pip install . in the readthedocs build environment

d8d3609

To fix `ModuleNotFoundError: No module named 'pygmt'`.

vercel bot temporarily deployed to Preview April 3, 2022 16:18 Inactive

seisman modified the milestones: 0.6.1, 0.7.0 Apr 9, 2022

Merge branch 'main' into vercel_to_readthedocs

4024311

vercel bot temporarily deployed to Preview June 15, 2022 04:18 Inactive

Remove vercel configurations and add readthedocs configurations in MA…

2423151

…NIFEST.in

vercel bot temporarily deployed to Preview June 15, 2022 04:35 Inactive

Update doc/maintenance.md to trigger builds in PR

afe3910

vercel bot temporarily deployed to Preview June 15, 2022 04:42 Inactive

Set canonical URL by setting html_baseurl

55a85e2

vercel bot temporarily deployed to Preview June 15, 2022 05:14 Inactive

Update contributing and maintenance guides

28aa23f

vercel bot temporarily deployed to Preview June 19, 2022 09:56 Inactive

seisman modified the milestones: 0.7.0, 0.8.0 Jun 19, 2022

weiji14 commented Jun 22, 2022

View reviewed changes

Only install packages required for building docs

d21acf9

seisman reviewed Jun 23, 2022

View reviewed changes

vercel bot temporarily deployed to Preview June 23, 2022 01:46 Inactive

Move the docs environment file to the ci directory

96e7aac

vercel bot temporarily deployed to Preview July 7, 2022 05:56 Inactive

seisman reviewed Jul 7, 2022

View reviewed changes

Merge branch 'main' into vercel_to_readthedocs

95b9788

seisman marked this pull request as ready for review July 11, 2022 09:43

vercel bot temporarily deployed to Preview July 11, 2022 09:43 Inactive

seisman added the needs review This PR has higher priority and needs review. label Jul 11, 2022

Merge branch 'main' into vercel_to_readthedocs

cdadd37

vercel bot temporarily deployed to Preview July 12, 2022 16:08 Inactive

maxrjones approved these changes Jul 29, 2022

View reviewed changes

Merge branch 'main' into vercel_to_readthedocs

41decc3

vercel bot temporarily deployed to Preview July 30, 2022 01:49 Inactive

seisman added final review call This PR requires final review and approval from a second reviewer and removed needs review This PR has higher priority and needs review. labels Jul 30, 2022

seisman merged commit d3b5fdc into main Jul 31, 2022

seisman deleted the vercel_to_readthedocs branch July 31, 2022 05:27

seisman removed the final review call This PR requires final review and approval from a second reviewer label Jul 31, 2022

maxrjones mentioned this pull request Oct 11, 2022

Link Checker Report on 2022-10-09 #2151

Closed

seisman mentioned this pull request Apr 9, 2024

Add a tutorial to add frames GenericMappingTools/gmt-examples#12

Merged

Esteban82 mentioned this pull request Apr 9, 2024

Migrate Continuous Documentation from Vercel to Readthedocs GenericMappingTools/gmt-examples#13

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate Continuous Documentation from Vercel to Readthedocs #1859

Migrate Continuous Documentation from Vercel to Readthedocs #1859

weiji14 commented Mar 31, 2022

vercel bot commented Mar 31, 2022 •

edited

Loading

seisman commented Apr 1, 2022

seisman commented Apr 1, 2022

weiji14 commented Apr 3, 2022

seisman commented Apr 3, 2022

weiji14 commented Apr 3, 2022

weiji14 commented Jun 10, 2022

seisman commented Jun 11, 2022

weiji14 commented Jun 11, 2022

seisman commented Jun 15, 2022

vercel bot commented Jun 15, 2022 •

edited

Loading

weiji14 Jun 22, 2022 •

edited

Loading

seisman Jun 23, 2022

seisman Jun 23, 2022

maxrjones Jun 23, 2022

seisman Jun 23, 2022

weiji14 Jun 23, 2022

weiji14 Jun 23, 2022 •

edited

Loading

seisman Jun 23, 2022 •

edited

Loading

seisman Jul 7, 2022

weiji14 Jul 11, 2022 •

edited

Loading

maxrjones left a comment

weiji14 commented Jul 31, 2022

seisman commented Jul 31, 2022

	mamba install gmt=6.3.0 numpy pandas xarray netCDF4 packaging \
	build ipython make myst-parser geopandas \
	sphinx sphinx-copybutton sphinx-design sphinx-gallery sphinx_rtd_theme

Migrate Continuous Documentation from Vercel to Readthedocs #1859

Migrate Continuous Documentation from Vercel to Readthedocs #1859

Conversation

weiji14 commented Mar 31, 2022

vercel bot commented Mar 31, 2022 • edited Loading

seisman commented Apr 1, 2022

seisman commented Apr 1, 2022

weiji14 commented Apr 3, 2022

seisman commented Apr 3, 2022

weiji14 commented Apr 3, 2022

weiji14 commented Jun 10, 2022

seisman commented Jun 11, 2022

weiji14 commented Jun 11, 2022

seisman commented Jun 15, 2022

vercel bot commented Jun 15, 2022 • edited Loading

weiji14 Jun 22, 2022 • edited Loading

Choose a reason for hiding this comment

seisman Jun 23, 2022

Choose a reason for hiding this comment

seisman Jun 23, 2022

Choose a reason for hiding this comment

maxrjones Jun 23, 2022

Choose a reason for hiding this comment

seisman Jun 23, 2022

Choose a reason for hiding this comment

weiji14 Jun 23, 2022

Choose a reason for hiding this comment

weiji14 Jun 23, 2022 • edited Loading

Choose a reason for hiding this comment

seisman Jun 23, 2022 • edited Loading

Choose a reason for hiding this comment

seisman Jul 7, 2022

Choose a reason for hiding this comment

weiji14 Jul 11, 2022 • edited Loading

Choose a reason for hiding this comment

maxrjones left a comment

Choose a reason for hiding this comment

weiji14 commented Jul 31, 2022

seisman commented Jul 31, 2022

vercel bot commented Mar 31, 2022 •

edited

Loading

vercel bot commented Jun 15, 2022 •

edited

Loading

weiji14 Jun 22, 2022 •

edited

Loading

weiji14 Jun 23, 2022 •

edited

Loading

seisman Jun 23, 2022 •

edited

Loading

weiji14 Jul 11, 2022 •

edited

Loading