The new refactor of the home page leaves it without a proper title and <title>&lt;no title&gt; &#8212; Read the Docs Blog</title> is shown on it at https://blog.readthedocs.com/

Hello! I saw the most recent post about RTD configuration files, there is a section about urllib3 and OpenSSL:

We plan to deploy these changes and start failing builds without a configuration file in September > 2023. This matches the period when urllib3 drops support for OpenSSL 1.1.1 which is the OpenSSL version installed by the build image used when
the project doesn’t specify a configuration file.

This mentions urllib3 dropping OpenSSL 1.1.1 in September 2023 and links to the issue, but in the issue it only mentions that the LTS release of OpenSSL 1.1.1 will no longer be supported by the OpenSSL team. urllib3 will continue working for a long time with OpenSSL 1.1.1.

I wonder if this was confused with urllib3 not supporting OpenSSL versions earlier than 1.1.1 in urllib3 v2.0 and Readthedocs was using a default build image that used OpenSSL 1.0.2 which was causing issues.

Let me know if I can help figure out any other confusing parts, there's a lot of numbers and different moving pieces. Thanks again for helping out urllib3 users!

cc @humitos @benjaoming @agjohnson

We have done good work on the documentation page about build.jobs and build.commands, https://docs.readthedocs.io/en/latest/build-customization.html. However, we haven't write a blog post announcing build.commands in beta state.

I think it's a good timing for this since we have been testing it during some months and it's a good feature as it is, even with the current limitation that it has.

We wrote a blog post about build.jobs that we can use as a reference: https://blog.readthedocs.com/user-defined-build-jobs/

Both before and after #188, margins have been off. It'd be nice to give them a bit more care. I think any improvement can be considered enough to close this issue and move on.

Margins:

• Around sidebar and content column
• Around headlines and paragraphs

now this sounds stupid, but i can't find the rendered version of this blog. it's not linked from rtfd.org or here.

I didn't thought too much about the content yet, but I'd love to see some of the nice graphs we are getting from Metabase in a blog post commenting how people is using our platform. It could be related with the science work that @benjaoming is doing too or something more generic, or both!

I tried creating a virtualenv, installing requirements.txt and make html, which is what the CI seems to do, but I get the following error:

(.venv) juanlu@arion2:~/Projects/RTD/blog$ make html
sphinx-build -b html -d _build/doctrees  -W . _build/html
Running Sphinx v1.7.9
loading pickled environment... not yet created
loading intersphinx inventory from https://docs.readthedocs.io/en/stable/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 221 source files that are out of date
updating environment: 221 added, 0 changed, 0 removed
/home/juanlu/Projects/RTD/blog/.venv/lib/python3.7/site-packages/sphinx/util/nodes.py:57: FutureWarning:                                                                                                                                      
   The iterable returned by Node.traverse()
   will become an iterator instead of a list in Docutils > 0.16.
  for classifier in reversed(node.parent.traverse(nodes.classifier)):
reading sources... [100%] welcome                                                                                                                                                                                                             
Skipping atom feed link rewrite due to errors...

Warning, treated as error:
/home/juanlu/Projects/RTD/blog/.venv/lib/python3.7/site-packages/sphinx/ext/autosummary/templates/autosummary/base.rst:3:Error in "currentmodule" directive:
maximum 1 argument(s) allowed, 3 supplied.

.. currentmodule:: {{ module }}
make: *** [Makefile:53: html] Error 2

I have exactly the same dependencies as this successful CI build: https://github.com/readthedocs/blog/runs/2239735141?check_suite_focus=true

@humitos pointed me out to https://github.com/wpilibsuite/sphinxext-opengraph/, which would be interesting to test across RTD as we noted. I think a good first place to add it would be our blog, since we usually share posts on social media, and having OpenGraph tags would make them look nicer with little effort, in principle.

However, we are using an ancient version of Sphinx in our blog, and the extension requires Sphinx 2.0 or greater. Therefore, we would need to upgrade it first. Therefore, this is blocked on #107.

It would be good to have a blog post explaining "How to do documentation versioning" and the different approaches that you can do.

There are some articles already,

• https://docs.readthedocs.io/en/latest/versions.html#how-we-envision-versions-working
• http://ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/#recommended-versioning-system

The problem that I feel with tags as documentation versions is that you are tied or "blocked" there and if you find a simple typo or a code example that doesn't work you can't fix it anymore because the tag is frozen and that doesn't worth a new release of the whole software.

Another example is that you can't change the theme or any Sphinx setting or Read the Docs YAML config option at all.

Mentioning this potential issues in the future could make the user to think twice what approach he/she want to follow when creating RTD versions for the documentation.

I used the little box on the blog saying " Sign up for our blog and we'll send you information about Sphinx and Read the Docs on a regular basis. " a while back, but I didn't receive anything. I expected some sort of automated email on the new blog posts, for example. If it is not automated, I propose we discuss about what to do with it :)

Our blog doesn't need a lot of new Sphinx features, but upgrading would help us adopt some extensions and possibly have other small benefits. However, I tried upgrading to Sphinx 2.4 and the HTML changed, so our styles broke:

Therefore, this would require a bit of work.

It would be nice to use the autolabel extension as suggested by @humitos

I have a very specific case to motivate it. Supposing you are writing a blog post that refers to a section in a previous blog post. This has already happened to me. I then have to edit the previous blog post to add a label. I can't recall the details, but I'm pretty sure it has made the RSS feed confused that previous entries are edited.

(Similar issues will continue to happen with Intersphinx if we blog posts refer docs that change later on, so it's still an issue we should pay attention to)

Since the jQuery removal might lead to silent breakage, it's a good idea to add some advice in a blog post:

• Mention the background, i.e. Sphinx 6
• sphinx-rtd-theme will not ship jQuery from version 2.0 (pending decision in readthedocs/sphinx_rtd_theme#1253)
• You need sphinxcontrib-jquery as a dependency onwards
• Consider also writing vanilla JS for simple use cases

Suggesting this outside of a newsletter for better publicity.

We tweeted about shot-scraper at https://twitter.com/readthedocs/status/1582763564376690689

It would be good to write a small blog post showing a real good use case. I was thinking that the blog post could use "Adding a custom domain on a Read the Docs project" as an example, where it documents the process and shows screenshots of the dashboard UI while explaining it.

• Blog post: https://simonwillison.net/2022/Oct/14/automating-screenshots/
• Documentation: https://shot-scraper.datasette.io/en/stable/

As suggested by @humitos, we could benefit from preview links added

Unrelated, would you mind adding https://github.com/readthedocs/actions/tree/main/preview so we can have a link to the rendered PR?

Originally posted by @humitos in #189 (review)

The blog's front page cuts off without any further guidance. It's possible to understand from the sidebar that we have very old posts, but it would be nice to click something at the end of the post list on index.html

Since /jobs/ is our most visited page, @MxRaCohen proposed some good ideas:

There’s gotta be something we can put in /jobs/ like “thank you so much for wanting to support RtD. While we don’t have any open positions you can support us in other ways like keeping [ads] on your project page, addressing a [first issue], or directly” (by buying merch or sponsoring something idk)

As per title. Numbers are not shown.

This is an announcement post for this feature. It can highlight some of the docs we've already written, and inline some of the neat examples we've figured out.

I would like the Blog to be more clear about our main areas of interest. We could have a side-bar explaining:

This blog is maintained by the Read the Docs core team.
You can read more about us here:

• Read the Docs for Business
• Read the Docs for Community

We should definitely do a "most popular Sphinx extensions" post, using our data & PyPI stats if we can find them. Also there's an interesting one around Sphinx version/theme adoption using our data & https://pepy.tech/project/sphinx & https://pepy.tech/project/sphinx_rtd_theme (edited)

Once we have search running in production, we should write a blog post. It should:

Tell users about new functionality (eg. all the fancy stuff SimpleQuerySearch does, with example search links)
Tell users how to test it
Ask for feedback and thoughts on improvement
We should aim to have this out by around July 15 or so, so that we have some time to get user feedback before the end of the GSOC.

Moved from readthedocs/readthedocs.org#4334

Blog post: https://blog.readthedocs.com/cancel-old-builds/

It would be good to update this blog post, or maybe better, write a new one with some updated numbers. Now, we know that around 10% of total builds per day are cancelled, which is a really good number to communicate. We could also related this to

• savings in $$ if we find a good metric to get this number
• CPU time saved (comparison between total build time per day) ¹

Builds cancelled per day	Build time per day

We got a bunch of love for this post: https://www.ethicalads.io/blog/2021/07/handling-100-requests-per-second-with-python-django/ -- we should do one for RTD. It can:

• Talk about our architecture (Scaling Groups, Postgres, CDN, S3)
• Highlight sponsors (AWS, Cloudflare)
• Talk about some performance issues we've hit (404 tracking, 404's in general :x)

We have done lots of interesting data collection in our metabase research. It would be neat to publish this, and share some of this data with the community. Not a ton of direction here, but curious what we can find in the data!

A couple ideas:

• What are the most popular sphinx extensions?
• Graphs of version usage over time. How do Sphinx/mkdocs/etc. versions get updated after a release?

This could also be a really great Twitter thread to start with, then migrate it into a blog post as we get engagement there.

We started using Plausible on our new website, we should eventually consolidate our blog as well. This blog repo will eventually be one with the website repo, or at least new blog content will be authored on the new website anyways, but consistency would help here.

This is probably the easiest analytics improvement, as I don't know we have much data in GA on our blog that we really care about at the moment.

wpilibsuite/sphinxext-opengraph#43 was fixed, see wpilibsuite/sphinxext-opengraph@54ea5eb and released as sphinx-opengraph 0.5.0.