Major issues with contribution on windows

[falOn-Dev]

I've been trying to contribute to frc-docs on my windows machine and I've been having a lot of issues, I was asked to put in an issue so I'm going to make a little list

1. source/extensions/redown.py line 164 must be commented out to build on windows
2. .rd files seem to be created randomly, I truly can't track down a cause for this, it doesn't happen during builds, lints, pulls, anything, they just seem to appear without any noticable cause
3. .\make lint doesn't seem to work (at least on windows) because it's linting as if the files are RST instead of Markdown.
4. the CI linting check gives incorrect line numbers, making finding things like whitespace really difficult.
5. When following the build guide for ubuntu in WSL, sphinx-build doesn't exist, even if you directly run pip install sphinx

[edited - changed bullet points to numbered points]

[calcmogul]

What error do you get for (1)?

[TheTripleV]

1. https://github.com/wpilibsuite/frc-docs/blob/main/source/_extensions/redown.py#L164 That line is for debugging. Normally the md is converted to rst in memory and sent straight to sphinx. This line also writes the files to disk with the .rd extension to make debugging easier. I accidentally left it uncommented in my most recent pr. My bad. The same debugging line exists while linting (https://github.com/wpilibsuite/frc-docs/blob/main/scripts/doc8_redown.py#L15) but is correctly commented out and supports windows. The uncommented version in redown.py doesn't work on windows because windows doesn't default to utf8 on file io.
2. The .rd files are created by the line in point 1. They stopped appearing when you commented out the line.
3. The linter is modified to preprocess all the files into rst before linting. It's supposed to lint them as rst. It's not working because you have autocrlf turned on. I happened to have it turned off when I initially tested this on Windows so never ran into it. The simplest fix for this is to remove carriage returns in the linter (.replace("\r", "")). I just tried this out in a windows vm with git.autocrlf=true and it works.
4. Yeah this makes it hard. I'll see if I can get the mapping closer to correct. Also, it's just documentation. I'm fine with ignoring things like extra whitespace or an extra newline at the end of the file. Since rst doesn't have autoformatting, it just makes it super annoying to contribute.
5. For most python tools nowadays, its better get to them via python as Dalton pointed out. So python -m sphinx-build (or py or py3 or python3 if thats what you use)

[falOn-Dev]

https://github.com/dzhu/rstfmt is this not an option for automatically formatting RST? or is it scuffed because of the weird MD -> RST stuff

[falOn-Dev]

What error do you get for (1)?

https://gist.github.com/falOn-Dev/b345c63db5c545a1fd93d99177c0b0fd

[TheTripleV]

https://github.com/dzhu/rstfmt is this not an option for automatically formatting RST? or is it scuffed because of the weird MD -> RST stuff

No, rstfmt was never an option, even with pure rst. It doesn't handle a bunch of directives and would need to be extended.

[sciencewhiz]

5. When following the build guide for ubuntu in WSL, sphinx-build doesn't exist, even if you directly run pip install sphinx

What version of ubuntu?

[sciencewhiz]

1 and 2 were fixed by #2733