Readthedocs.org: Artifacts aren't cleaned when changing from Sphinx to Mkdocs

[raoshridhar90]

Details

• Read the Docs project URL: https://readthedocs.org/projects/wait/
• Build URL (if applicable):
• Read the Docs username (if applicable): shridhar.rao

Expected Result

HTML copy of what I see on View Docs

Actual Result

HTML copy is of Sphinx document I was trying out

P.S: I am absolutely brand new at this because I know nothing about Python. I'm just a technical writer trying to find a way to document my company's backend.

[stsewd]

HTML copy of what I see on View Docs

Sorry, I don't understand your issue, can you please clarify a little more?

We have this getting started guides for sphinx or mkdocs here https://docs.readthedocs.io/en/latest/intro/getting-started-with-sphinx.html https://docs.readthedocs.io/en/latest/intro/getting-started-with-mkdocs.html

[davidfischer]

I'm pretty certain this issue is because the documentation type is set to Sphinx instead of MkDocs. In the settings for your project, you need to change the documentation type.

[raoshridhar90]

HTML copy of what I see on View Docs

Sorry, I don't understand your issue, can you please clarify a little more?

We have this getting started guides for sphinx or mkdocs here https://docs.readthedocs.io/en/latest/intro/getting-started-with-sphinx.html https://docs.readthedocs.io/en/latest/intro/getting-started-with-mkdocs.html

Hey @stsewd, I would be happy to do so.

What I meant (and should have been clear about) is that ReadTheDocs is building the document, and I can see Markdown that I changed and uploaded on to GitHub and imported onto ReadTheDocs in the View Docs tab. But when I go to download the document as an HTML or PDF, it shows me the Sphinx page that I have attached as a screenshot. I followed all the instructions in the document and I think I've done everything fine.

If I have the time, I will update your documentation (if open source) because there are big gaps in it in my opinion as a technical writer.

[raoshridhar90]

I'm pretty certain this issue is because the documentation type is set to Sphinx instead of MkDocs. In the settings for your project, you need to change the documentation type.

Hey @davidfischer, I thought that was the problem too, the first time I encountered this. But in this current generation instance, it is Markdown as shown below.

[davidfischer]

If I have the time, I will update your documentation (if open source) because there are big gaps in it in my opinion as a technical writer.

I wrote this relatively recently and would love help on filling in the gaps. It is open source and you can find the getting started with mkdocs guide here.

Hey @davidfischer, I thought that was the problem too, the first time I encountered this. But in this current generation instance, it is Markdown as shown below.

Actually when I look at this, I don't yet see what the problem is. Based on your repository, I think it should generate HTML like this. Maybe I don't yet fully understand the problem.

[stsewd]

So, I think I understand the problem here, your project is mkdocs type, mkdocs doesn't support pdf or epub generation. But, I can see that your project does have links to download pdf and epub.

So, I saw your builds, and I found that one of those was using sphinx, there were generated pdf and epub files. Then, when building back with mkdocs, those files aren't removed, so your project keeps serving the old sphinx generated files.

We should clean that files when building with mkdocs.

[raoshridhar90]

@stsewd thank you! How do I clean those files is my question.

[stsewd]

I think a workaround can be building with sphinx again, but un-selecting the epub and pdf generation, then if you change back to mkdocs, those files should be removed. But this is a bug on rtd and we should fixed it

[raoshridhar90]

What if I get rid of Sphinx? As someone who knows very little about Python, Sphinx has been excessively complicated for me. But I'll try your suggestion and close this open query when I do it. However, it's late in India so I'll get to it tomorrow!

Thanks!

On Oct 18, 2018 at 01:48, [e-mail]> wrote:

I think a workaround can be building with sphinx again, but un-selecting the epub and pdf generation, then if you change back to mkdocs, those files should be removed. But this is a bug on rtd and we should fix it.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHubhttps://github.com/rtfd/readthedocs.org/issues/4764#issuecomment-430773333, or mute the threadhttps://github.com/notifications/unsubscribe-auth/ANTtKBSxTFo8K5Nalxc-VZjFoG_J8yQ9ks5ul5CPgaJpZM4XeDAw.

[raoshridhar90]

If I have the time, I will update your documentation (if open source) because there are big gaps in it in my opinion as a technical writer.

I wrote this relatively recently and would love help on filling in the gaps. It is open source and you can find the getting started with mkdocs guide here.

Hey @davidfischer, I thought that was the problem too, the first time I encountered this. But in this current generation instance, it is Markdown as shown below.

Actually when I look at this, I don't yet see what the problem is. Based on your repository, I think it should generate HTML like this. Maybe I don't yet fully understand the problem.

Hey @davidfischer, I will definitely do it when I figure out this problem. Also, I think there are gaps in the ReadTheDocs documentation. MkDocs seems pretty straightforward. However, for now, the link you attached seems to be broken, so I don't really know what you mean. Haha, wow. This is confusing.

[raoshridhar90]

I think a workaround can be building with sphinx again, but un-selecting the epub and pdf generation, then if you change back to mkdocs, those files should be removed. But this is a bug on rtd and we should fixed it

@stsewd, I tried that but same problem again. Doesn't seem to be making a difference. I hope that bug is ironed out soon then!

[davidfischer]

However, for now, the link you attached seems to be broken

That's weird. It seems to be working for me even in incognito!

I still don't seem to understand this issue. I don't see the links to download an epub or PDF anymore.

[stsewd]

@davidfischer If I recall correctly, we don't generate any type of download for Mkdocs projects, the download section shouldn't be there.

@raoshridhar90 rtd built the html files for download on sphinx always, it can only be disabled using a configuration file https://docs.readthedocs.io/en/latest/yaml-config.html#supported-settings The pdf and epub aren't there, so the previous step worked! So, I see two workarounds here, using a config file to not build any format (and repeat the previous step of change the doctype to sphinx), or just recreating your project and using mkdocs as the doctype from the beginning

[raoshridhar90]

However, for now, the link you attached seems to be broken

That's weird. It seems to be working for me even in incognito!

I still don't seem to understand this issue. I don't see the links to download an epub or PDF anymore.

@davidfischer, it's working fine now. Thanks! If @stsewd is saying it shouldn't be generating any download, then I don't know why this is. Any explanations, @stsewd? Also, I disabled epub and PDF, that's why you can't see anything.

@stsewd, I actually decided to check out Sphinx as my documentation base and it wasn't as hard as I thought. The only issue is that ReadTheDocs is not applying its own theme to the Sphinx created HTML. I'll have to play around with it, I guess? Well, the PDF and Epub aren't there because I disabled them but if you don't allow downloads in Markdown, then there's no point for me to use Markdown, right?

[stsewd]

If @stsewd is saying it shouldn't be generating any download, then I don't know why this is. Any explanations, @stsewd?

Is because of the same problem, you built wih sphinx once, rtd generated the download files, then when changing to mkdocs, rtd doesn't clean the previous files.

• We don't provide any downloads on Mkdocs (that's a limitation of mkdocs, not from rtd).
• You can use markdown with sphinx (downloads here are supported)

[raoshridhar90]

If @stsewd is saying it shouldn't be generating any download, then I don't know why this is. Any explanations, @stsewd?

Is because of the same problem, you built wih sphinx once, rtd generated the download files, then when changing to mkdocs, rtd doesn't clean the previous files.

• We don't provide any downloads on Mkdocs (that's a limitation of mkdocs, not from rtd).
• You can use markdown with sphinx (downloads here are supported)

Haha, cool. I'll play around with Sphinx a bit. Thank you so much for all the help. I hope you get that bug sorted out. Also, thank you so much; you guys are much friendlier and much more helpful than StackOverflow. Those dudes are rude!

[stsewd]

Just linking to the related code to look at later

https://github.com/rtfd/readthedocs.org/blob/a4291d17728b8df6b7a9ce57537c5d620416e485/readthedocs/projects/tasks.py#L775-L816

[raoshridhar90]

@stsewd, I migrated completely to Sphinx from Mkdocs, but thanks for all the help!

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stsewd]

Not stale, just low priority :) bot

[stsewd]

I can't replicate this anymore locally or in production. It was fixed https://github.com/rtfd/readthedocs.org/pull/4947/ in with the delete_unsynced_media arg