Stop creating a conf.py automatically and doing magic around README handling #5609

saadmk11 · 2019-04-18T11:03:45Z

I need some input about the README handling. if that's what we want or not?

…around README handling

stsewd

We need to remove the autocreated mkdocs.yaml for mkdocs projects too https://github.com/rtfd/readthedocs.org/blob/43c1ba7e8b65bc3bb5a8b2d7b7f6de94dfa91b44/readthedocs/doc_builder/backends/mkdocs.py#L88-L91

The index page generation should stay, this is another issue we need to resolve in another PR (right now we should generate an index if we don't find one)

readthedocs/doc_builder/backends/sphinx.py

saadmk11 · 2019-04-24T19:19:39Z

@stsewd Updated the PR according to your suggestions.

readthedocs/rtd_tests/tests/test_doc_builder.py

saadmk11 · 2019-04-25T09:21:31Z

@stsewd Updated the PR

saadmk11 · 2019-05-09T12:59:59Z

resolved conflicts

stsewd

Just a few details, this should be ready for merge after that.

readthedocs/doc_builder/exceptions.py

readthedocs/rtd_tests/tests/test_doc_builder.py

….org into readme-creation-fix

saadmk11 · 2019-05-13T18:47:20Z

@stsewd Updated the PR :)

stsewd

Thanks!

readthedocs/rtd_tests/tests/test_doc_builder.py

humitos

Thanks! Changes look good to me.

I'm a little worried about current projects that are building properly,

without a conf.py file
with a README file instead of a index.rst

What is our plan for those projects?

I'm marking as "Request changes" because of this reason to discuss what we want to do with those projects before merging it.

readthedocs/doc_builder/backends/sphinx.py

humitos · 2019-05-14T09:18:20Z

readthedocs/doc_builder/exceptions.py

@@ -76,3 +76,7 @@ class MkDocsYAMLParseError(BuildEnvironmentError):
        'The "{config}" config from your MkDocs YAML config file has to be a '
        'a list of relative paths.',
    )
+    NOT_FOUND = ugettext_noop(
+        'A configuration file was not found. '
+        'Make sure you have a "mkdocs.yaml" file in your repository.',


Not sure if it matters, but official MkDocs uses mkdocs.yml to refer this file. I suppose it's better to follow their convention here.

@humitos Fixed. :)

stsewd · 2019-05-14T14:48:25Z

What is our plan for those projects?

@humitos It was decided that if those project don't build locally, they shouldn't build in rtd neither. See #2483 (comment)

humitos · 2019-05-14T15:55:47Z

@stsewd I think that is valid for new projects, but I don't think we want to break all the ones that are already building properly. Also, that seems like a comment from David to me, not a decision made.

Do we know how many projects that matches the conditions that I mentioned are currently building? I suppose that at least we should contact them and make a deprecation plan giving them some time to migrate.

humitos · 2019-05-30T12:26:24Z

We decided that,

we want to log.info the projects that are using this these features
communicate with them to help on the migration

Once we have collected this data and we gave some time to them to migrate, we can merge this PR. I'm marking as blocked until then.

Before removing this, we want to collect some info to communicate this change to users. Related readthedocs#5609

humitos · 2023-07-04T11:37:56Z

We are ready to move forward with the plan I wrote in my previous comment #5609 (comment)

So, the first step here is to add log lines to know what are the projects where we are creating a conf.py or a mkdocs.yaml file. It seems we already have this in place:

Sphinx:

NR: https://onenr.io/0MR2yz7qbwY

Code:

readthedocs.org/readthedocs/doc_builder/backends/sphinx.py

Lines 118 to 122 in 37650de

    
           log.info( 
        
               'Creating default Sphinx config file for project.', 
        
               project_slug=self.project.slug, 
        
               version_slug=self.version.slug, 
        
           )

MkDocs:

NR: https://onenr.io/0oQDKbpp5jy

Code:

readthedocs.org/readthedocs/doc_builder/backends/mkdocs.py

Lines 121 to 125 in 37650de

    
           log.info( 
        
               'Creating default MkDocs config file for project.', 
        
               project_slug=self.project.slug, 
        
               version_slug=self.version.slug, 
        
           )

It seems we are ready to start contacting these users about the removal of this feature.

…adme-creation-fix

I updated the PR with the latest changes

ericholscher · 2023-07-11T18:29:41Z

@humitos This needs to be merged after Aug 28 right?

humitos · 2023-07-12T08:43:44Z

Yes, https://blog.readthedocs.com/doctool-without-configuration-file/

ericholscher · 2023-07-12T15:41:43Z

@humitos Great, I've added it to the sprint for that timeframe 👍

…adme-creation-fix

readthedocs/doc_builder/backends/sphinx.py

…adme-creation-fix

saadmk11 added 2 commits April 18, 2019 17:00

Stop creating a conf.py file automatically for users and doing magic …

52654fc

…around README handling

remove readme text

24e0d80

stsewd reviewed Apr 24, 2019

View reviewed changes

readthedocs/doc_builder/backends/sphinx.py Show resolved Hide resolved

readthedocs/doc_builder/backends/sphinx.py Outdated Show resolved Hide resolved

Auto generating mkdocs.yaml removed

beac3a6

stsewd reviewed Apr 24, 2019

View reviewed changes

readthedocs/rtd_tests/tests/test_doc_builder.py Outdated Show resolved Hide resolved

stsewd mentioned this pull request Apr 24, 2019

Move file validations out of the config module #5627

Merged

create_index added

6270919

Merge branch 'master' into readme-creation-fix

c749184

stsewd reviewed May 13, 2019

View reviewed changes

readthedocs/doc_builder/exceptions.py Outdated Show resolved Hide resolved

readthedocs/rtd_tests/tests/test_doc_builder.py Show resolved Hide resolved

readthedocs/rtd_tests/tests/test_doc_builder.py Outdated Show resolved Hide resolved

saadmk11 added 3 commits May 14, 2019 00:21

fixed error msg

49e1e72

tests updated

98c8310

Merge branch 'readme-creation-fix' of github.com:saadmk11/readthedocs…

e7549cb

….org into readme-creation-fix

stsewd approved these changes May 13, 2019

View reviewed changes

readthedocs/rtd_tests/tests/test_doc_builder.py Outdated Show resolved Hide resolved

stsewd requested a review from a team May 13, 2019 20:39

humitos previously requested changes May 14, 2019

View reviewed changes

Updated Error msg

61c7d44

humitos added the Needed: design decision A core team decision is required label May 20, 2019

humitos added Status: blocked Issue is blocked on another issue and removed Needed: design decision A core team decision is required labels May 30, 2019

stsewd added a commit to stsewd/readthedocs.org that referenced this pull request Jun 12, 2019

Add logging in magic methods

56b1915

Before removing this, we want to collect some info to communicate this change to users. Related readthedocs#5609

stsewd mentioned this pull request Jun 12, 2019

Add logging in magic methods #5795

Merged

humitos removed the Status: blocked Issue is blocked on another issue label Jul 4, 2023

humitos mentioned this pull request Jul 10, 2023

Stop creating a conf.py/mkdocs.yaml file automatically for users and doing magic #2483

Closed

Merge branch 'main' of github.com:readthedocs/readthedocs.org into re…

262871d

…adme-creation-fix

humitos requested a review from a team as a code owner July 11, 2023 14:33

humitos self-requested a review July 11, 2023 14:33

humitos added 2 commits July 11, 2023 16:47

Lint

e97ca61

Test: remove old test

4bbbc1e

humitos requested a review from stsewd July 11, 2023 14:53

Lint

428f72e

humitos added the Status: blocked Issue is blocked on another issue label Jul 12, 2023

Delete conf.py template

01c9f6e

humitos mentioned this pull request Jul 31, 2023

Build: do not auto-create conf.py Sphinx file #10583

Closed

Merge branch 'main' of github.com:readthedocs/readthedocs.org into re…

47ddaaa

…adme-creation-fix

humitos mentioned this pull request Aug 1, 2023

Deprecations: list of all past and ongoing deprecations #10587

Open

Build: fail the build if docs/conf.py doesn't exist

eef1165

humitos mentioned this pull request Aug 16, 2023

Build: fail build if conf.py file doesn't exist #10627

Closed

stsewd reviewed Aug 16, 2023

View reviewed changes

readthedocs/doc_builder/backends/sphinx.py Outdated Show resolved Hide resolved

readthedocs/doc_builder/backends/sphinx.py Outdated Show resolved Hide resolved

humitos added 2 commits August 17, 2023 15:55

Build: raise exception if no config file

96621fd

Merge branch 'main' of github.com:readthedocs/readthedocs.org into re…

8c0442e

…adme-creation-fix

humitos merged commit 97b3b25 into readthedocs:main Aug 22, 2023
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Stop creating a conf.py automatically and doing magic around README handling #5609

Stop creating a conf.py automatically and doing magic around README handling #5609

saadmk11 commented Apr 18, 2019 •

edited by humitos

Loading

stsewd left a comment

saadmk11 commented Apr 24, 2019

saadmk11 commented Apr 25, 2019

saadmk11 commented May 9, 2019

stsewd left a comment

saadmk11 commented May 13, 2019

stsewd left a comment

humitos left a comment

humitos May 14, 2019

saadmk11 May 14, 2019

stsewd commented May 14, 2019

humitos commented May 14, 2019

humitos commented May 30, 2019

humitos commented Jul 4, 2023

ericholscher commented Jul 11, 2023

humitos commented Jul 12, 2023

ericholscher commented Jul 12, 2023

Stop creating a conf.py automatically and doing magic around README handling #5609

Stop creating a conf.py automatically and doing magic around README handling #5609

Conversation

saadmk11 commented Apr 18, 2019 • edited by humitos Loading

stsewd left a comment

Choose a reason for hiding this comment

saadmk11 commented Apr 24, 2019

saadmk11 commented Apr 25, 2019

saadmk11 commented May 9, 2019

stsewd left a comment

Choose a reason for hiding this comment

saadmk11 commented May 13, 2019

stsewd left a comment

Choose a reason for hiding this comment

humitos left a comment

Choose a reason for hiding this comment

humitos May 14, 2019

Choose a reason for hiding this comment

saadmk11 May 14, 2019

Choose a reason for hiding this comment

stsewd commented May 14, 2019

humitos commented May 14, 2019

humitos commented May 30, 2019

humitos commented Jul 4, 2023

ericholscher commented Jul 11, 2023

humitos commented Jul 12, 2023

ericholscher commented Jul 12, 2023

saadmk11 commented Apr 18, 2019 •

edited by humitos

Loading