I’ve been trying. I like to think of myself as pretty smart. I’ve spent a lot of hours and a lot of OpenAI’s server bandwidth trying to figure these out. But, man, I just hit a wall with these errors that seem inconsistent and unsolvable.
I would very much appreciate an hour or two of someone’s time on their schedule to sit down on this.
This is just a tiny sample of the kinds of things I hit. Duplicate label errors in a couple files that are set up the same way as all the other files around them (with an anchor and a title) and the other files arent’ erroring. Duplicate explicit target name when there is only one of those name in the links.rst file and I haven’t touched that file. A bunch of unknown document errors when I think I’m using the right doc: syntax to reference docs, and I see it working in other areas of the documentation.
I’m happy to share the knowledge once I get it and bring other people into the documentation fold, but looking for a little community support first! Thanks!
One tricky thing in Sphinx is that there are several forms that are capable of producing targets. In this case, both the label and the heading are producing a target (with the same name):
.. _edX Open Learning XML Guide:
############################
EdX Open Learning XML Guide
############################
What this guy says I managed to solve some warnings in your PR by removing the .. _Overview of Content Experiments: and . _Courses with Multiple Content Experiments: labels. I also fixed the .. include:: ../../../links/links.rst by replacing it with .. include:: ../../links.txt. Now facing a different warning: source/educators/migration_wip/links/links.rst:602:Duplicate explicit target name: "edx open learning xml guide".. This is because there are other links with the same name elsewhere.
Compiling the docs takes forever though, and I don’t have time to investigate further. Good luck!
Hey @john_curricume - I’m pretty underwater this week, but pressure should be lessened by the end of next week. I’ll try to help where I can, and feel free to tag me on any PR - particularly any improving our documentation to make this easier for others.
Thanks @Tim_McCormack@regis@sarina this is helpful. There must have been some different rules in the legacy edx.org docs, because they all have that syntax with two titles. But I can see that it doesn’t exist in our Open edX docs. I’ll give this another go soon and report back with how many errors it fixes.
I’m also trying to make sense of errors that sphinx will throw one time, and then go away (without changes). Good example below. It complains that a :doc: reference is unknown. But the doc exists and it is right in the same directory. I build again and it works.
I can’t understand if I’m fixing the error by running ‘make html’ twice, or just suppressing it and it’ll come back to bite me later.
Reviewing objects.inv has been hugely helpful: sphinx.ext.intersphinx – Link to other projects’ documentation — Sphinx documentation
That’s a catalog of all the available Ref links and Doc links and how Sphinx reads them.
If the link you want to use is missing from objects.inv, you’ve got an issue.
If the link you want to use is duplicated (not unique) in objects.inv, you’ve got an issue.
Seems like the way legacy Edx docs was set up is leading to issues when migrating to Open edX Docs. Still parsing out exactly the reason but EdX docs is a bunch of separate projects, and they use … include:: statements to reference documents in other projects, it seems. That seems to be causing issues in Open edX docs. Since everything is in the same project, using that include statement leads to duplicate Refs and Docs.
Best as I can understand it so far. Still working on it…
Alright, yes, I think I’ve boiled down the core of the issue.
Legacy edX ReadTheDocs is basically a compilation of several Sphinx projects. Each with their own build folder, links files, objects.inv, etc.
New docs.openedx.org is more of a monolith, with a single build folder, links file, objects.inv, etc.
In Legacy docs, many times when a doc (doc A) wanted to reference a doc in another project (doc B), then it could use this kind of syntax to do so:
.. include:: ../../path/to/docB.rst
And I think because of the multi-project structure, that didn’t cause an issue.
But in docs.edx.org that causes an issue. Because all our docs start with a title. Like this:
Title Goes Here
#####################################################
And when docA has a title, and docB references docA with the .. include syntax, then Sphinx creates two references and then throws an error for a duplicate reference.
I’m not sure how to fix this. using a :doc: or :ref: syntax could create links to the docs (e.g. docB from docA), but it wouldn’t be the same as actually writing out the content, as legacy ReadtheDocs does.
Any ideas @regis@Tim_McCormack@sarina ?
As far as I understand, you must avoid the situation where the same document is included twice in different pages. Included documents should also not be built.
This is where I invoke @feanil - he set up the docs.openedx.org structure, and I would assume has a reasoning for this configuration (and hopefully, a way around it)
What’s the reason for wanting the content duplicated on multiple pages instead of linking to one page that has the content? I believe what you want to do is possible but I’m trying to understand why we want the duplicate instead of having a canonical copy that we link to from multiple places for a piece of content.
I managed to solve some warnings in your PR by removing the 