Conversation
Author
|
The built docs are at https://tech-squares-member-db.readthedocs.io/en/branch-docs/installing.html right now |
- Update to a newer ReadTheDocs build OS
- Update to Sphinx 8.2 (or newer), which adds the `:collapsible:` option
which is used by upcoming content changes
- Build PDF and epub docs, mostly because it's easy
- Bump the copyright date
- Add a Sphinx extension for Django
- Add the deps from INSTALLED_APPS to `docs/requirements.txt`, since
Sphinx now tries to do Django setup
- Similarly, create `local.py` if it doesn't exist already so that
settings can be imported
- Mock some more files that don't get processed properly
- `squaresdb.urls` and `squaresdb.wsgi` both have some
Django-related errors, and while those might be fixable, there's
not much in those files to document, so skipping them seems
easiest
- Fix non-mock Sphinx warnings
- Set `language`
- Disable `html_static_path` since we don't use it
We had a couple people trying to set SquaresDB up on Windows, and this fixes a bunch of the issues they were running into. - Use `#!/usr/bin/env python`, which matches most of our other shebang lines, instead of `#!/usr/bin/env python3`, which would require people to have both `python` and `python3` to run all the scripts (people generally do, so it's mostly fine, but it seems a little silly) - Use `getpass.getuser()`[1] to find the current user, instead of checking `LOGNAME` and the `pwd` module -- `getuser` implements a very similar "check some env vars, then optionally `pwd`" algorithm but with more env vars, more concisely, and more portably (`pwd` is only available on Linux, not Windows, while `getpass` is available on almost all platforms) - Explicitly prefix `python` when running `manage.py`, instead of depending on the shebang line -- AFAICT shebang lines don't work on Windows [1] https://docs.python.org/3/library/getpass.html#getpass.getuser
- Add some guidance on how to install on Windows
- More clearly call out what needs to be done by hand and what's context
or handled automatically
- Hide the scripts.mit.edu install docs since they don't work
- Note that this uses the `:collapsible:` option, which is new in
Sphinx 8.2, which we recently upgraded to
- Dropdowns from sphinx-design
(https://sphinx-design.readthedocs.io/en/latest/dropdowns.html)
would also work, but requiring new Sphinx seems preferable to
requiring a third-party extension (though I think the built-in
feature looks worse)
- Format the warning text more clearly
- More clearly state that SSO isn't needed for a dev server
|
Code Review complete. Looks good. We may want to also include some setup of vscode required extensions, but as discussed, we can do that in a separate PR. |
Author
|
Thanks! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
With new Windows devs, I've gone through and made a bunch of updates to the docs (both toolchain and content) as well as made updates to improve Windows compat.