docs: Add a basic how-to for switching to the new theme. #246
Conversation
With https://github.com/openedx/edx-sphinx-theme/issues/184 we deprecate the edx-sphinx-theme so provide some docs for how people can migrate to the new theme.
feanil
force-pushed
the
feanil/theme_migration_how_to
branch
from
f197e12 to
54d3490
Compare
| - edx-sphinx-theme | ||
| + sphinx-book-theme | ||
|
|
||
| #. Run ``make upgrade`` |
There was a problem hiding this comment.
Is there a likelihood that something might go wrong here?
There was a problem hiding this comment.
I don't expect it to go wrong but I think once we have people try it on a few more repos, we can probably integrate feedback if there are common issues.
|
|
||
| html_theme_options = { | ||
|
|
||
| "repository_url": TODO: Add a URL Here, |
There was a problem hiding this comment.
| "repository_url": TODO: Add a URL Here, | |
| "repository_url": "https://github.com/openedx/the-name-of-your-repo", |
This entry and the next could use some explanation
| "use_repository_button": True, | ||
| "use_issues_button": True, | ||
| "use_edit_page_button": True, | ||
| "extra_footer": """ |
There was a problem hiding this comment.
This one is complicated, and shouldn't be changed, correct?
| # Set the DJANGO_SETTINGS_MODULE if it's not set. | ||
| # Only if your project has a dependency on Django | ||
| if not os.environ.get('DJANGO_SETTINGS_MODULE'): | ||
| os.environ['DJANGO_SETTINGS_MODULE'] = 'test_utils.test_settings' |
There was a problem hiding this comment.
This might also need some explanation.
There was a problem hiding this comment.
Added some more, let me know what you think.
Co-authored-by: Ned Batchelder <[email protected]>
| "repository_url": TODO: Add a github URL Here, for example https://github.com/openedx/repo-name, | ||
| "repository_branch": TODO: Add the correct branch, for example 'main', | ||
| "path_to_docs": "docs/", | ||
| "logo_only": True, |
There was a problem hiding this comment.
Version 1.0.1 of sphinx-book-theme is complaining about logo_only being an "unsupported theme option". Should this be removed?
There was a problem hiding this comment.
ah, yea good call I created #345 to fix this.
With openedx/public-engineering#200 we deprecate
the edx-sphinx-theme so provide some docs for how people can migrate to
the new theme.