Deprecation: stop auto-finding conf.py/mkdocs.yml from the repository

[humitos]

We currently have code that automatically finds a conf.py on the repository when there is no sphinx.configuration defined ( (https://docs.readthedocs.io/en/stable/config-file/v2.html#sphinx-configuration). We should remove this auto-finding and make sphinx.configuration to have a better default (like docs/conf.py) or make it always required.

Note: the same happens for mkdocs.yml and mkdocs.configuration

readthedocs.org/readthedocs/projects/models.py

Lines 944 to 962 in a23bc26

	files = self.find('conf.py', version)
	if not files:
	files = self.full_find('conf.py', version)
	if len(files) == 1:
	return files[0]
	for filename in files:
	# When multiples conf.py files, we look up the first one that
	# contains the `doc` word in its path and return this one
	if filename.find('doc', 70) != -1:
	return filename
	# If the project has more than one conf.py file but none of them have
	# the `doc` word in the path, we raise an error informing this to the user
	if len(files) > 1:
	raise ProjectConfigurationError(
	ProjectConfigurationError.MULTIPLE_CONF_FILES,
	)
	raise ProjectConfigurationError(ProjectConfigurationError.NOT_FOUND)

I created a Metabase query for and I found ~950 projects without specifying sphinx.configuration in the last 180 days.

[agjohnson]

It might also make sense to first inspect the number of projects that are flagged as spam. This could drop the number of projects considerably too.

[humitos]

I checked that query today and it returned ~400 projects only.

[agjohnson]

Is that 400 spam projects or 400 projects down from the original 950 projects? The query is stuck for me.

[humitos]

Total projects without filter then from spam

[humitos]

I checked this again today by making the query directly on the Telemetry database because Metabase times out when extending the date range:

SELECT
  DISTINCT data->'project'->>'slug' as slug
FROM
  "telemetry_builddata"
​WHERE
  NOT data->'config'->'user'->'sphinx' ? 'configuration'
;

Then, I filtered those slugs by "active" organizations and not spam projects. The results are:

• 22 projects on commercial
• 1202 projects on community

The next steps here are:

• Write a small blog post with specific dates
• Send an email to these users
• Add an if in the code to don't auto find these files after the deprecation date
• Delete the code that auto find these files

[agjohnson]

In Q4 we should send some emails out.

[ericholscher]

I checked this again today by making the query directly on the Telemetry database because Metabase times out when extending the date range:

SELECT
  DISTINCT data->'project'->>'slug' as slug
FROM
  "telemetry_builddata"
​WHERE
  NOT data->'config'->'user'->'sphinx' ? 'configuration'
;

Then, I filtered those slugs by "active" organizations and not spam projects. The results are:

• 22 projects on commercial
• 1202 projects on community

The next steps here are:

• Write a small blog post with specific dates
• Send an email to these users
• Add an if in the code to don't auto find these files after the deprecation date
• Delete the code that auto find these files

We merged the blog post here: readthedocs/website#342

I think we still need to send out the email to these folks.

[humitos]

@ericholscher do you want to quickly write the content of the email? I can send it after that. I sent you an invitation for collaboration on https://hackmd.io/QW2lFsFQTva5_WTN-a6i_A. It contains the text from a previous email as an initial idea for the structure.

[ericholscher]

@humitos updated the email 👍

[humitos]

Email sent 📧