|
1 | 1 | *FIRST* Tech Challenge Documentation Project |
2 | 2 | ========================================== |
3 | | - |
4 | 3 |   |
5 | 4 |
|
6 | 5 | This GitHub project is a work-in-progress for FTC documentation. |
7 | 6 |
|
8 | | -The website is available at https://ftc-docs.firstinspires.org |
9 | | - |
10 | 7 | # Contributing |
11 | 8 |
|
12 | | -We are always looking for help improving FTC Docs. For more infomration on contributing |
13 | | -consult the [contributing section](https://ftc-docs.firstinspires.org/contrib/index.html) in FTC Docs. |
| 9 | +## Prerequisites |
| 10 | + |
| 11 | +- GitHub Account |
| 12 | +- Git Installed on Local Machine (for local method) |
| 13 | + |
| 14 | +### Windows software dependencies (typically preinstalled on a Linux distro) |
| 15 | + |
| 16 | +- GitForWindows: https://gitforwindows.org/ |
| 17 | +- Chocolatey for installing make: https://chocolatey.org/install#individual |
| 18 | +- make: https://community.chocolatey.org/packages/make |
| 19 | + |
| 20 | +## Local Method |
| 21 | + |
| 22 | +1. Create fork of FtcDocs Project as shown [here](https://docs.github.com/en/get-started/quickstart/fork-a-repo) keeping the name of the repo the same |
| 23 | +2. Clone fork of project replacing `<NAME>` with your username |
| 24 | + |
| 25 | + `git clone https://github.com/<NAME>/ftcdocs.git` |
| 26 | +3. Install Python from [here](https://www.python.org/downloads/) |
| 27 | +4. Install Pip following [these](https://pip.pypa.io/en/stable/installation/) instructions |
| 28 | +5. Change directory to root project and install dependencies |
| 29 | + - `cd ftcdocs` |
| 30 | + - `pip install -r docs/requirements.txt` |
| 31 | +6. Make desired changes to project. Remember to follow style guide shown [here](https://docs.wpilib.org/en/stable/docs/contributing/frc-docs/style-guide.html) |
| 32 | +7. Install dependencies for PDF |
| 33 | + - Ubuntu/Debian: `xargs -a dependencies sudo apt install -y` |
| 34 | + - Windows: Install MiKTeX from [here](https://miktex.org/download) |
| 35 | +8. Build project by executing following commands in `docs\` folder of project |
| 36 | + - HTML: `make html` |
| 37 | + - Autobuild HTML: `make autobuild` |
| 38 | + - PDF: `make latexpdf` |
| 39 | + - Link: `make linkcheck` |
| 40 | +9. View Result (html) |
| 41 | + - Open `docs\build\html\index.html` in a browser of your choice |
| 42 | + - To create local http server execute `python3 -m http.server 7350` in `docs\build\html\index.html` and view result [here](http://localhost:7350). If you are using the Autobuild option this server will be automatically created and updated with most changes to rst files. Some changes will not be transferred like images and will require a `make clean`. |
| 43 | +10. Commit changes and push after desired result has been achieved |
| 44 | + - `git commit -a -m <MESSAGE>` replace <MESSAGE> with your commit message |
| 45 | + - `git push` |
| 46 | +11. [Create](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) a Pull Request to upstream repository. Make sure to be concise in your PR title and description. |
| 47 | + |
| 48 | +## Cloud Method |
| 49 | + |
| 50 | + |
| 51 | +1. Create fork of FtcDocs Project as shown [here](https://docs.github.com/en/get-started/quickstart/fork-a-repo) |
| 52 | +2. Ideally you should follow a feature based branch system. This means that you should create a new branch every time you are thinking of adding a new feature. This will insure that the main branch stays identical to upstream. |
| 53 | + 1. Click the drop down menu that says the branch you are currently working on (default is main) towards the top but slightly to the left |
| 54 | + 2. Type in what you wish to name your branch. It should be short and concise while also being able to convey to others what feature this branch has |
| 55 | + 3. Next click `Create branch: [name of branch] from ‘main’` |
| 56 | +3. Although you can view changes made in the Github preview this can be incorrect and is often incomplete. To give an accurate view of what your changes look like you will want to make your own Read The Docs site to preview your changes. To do this follow the instructions given [here](https://docs.readthedocs.io/en/stable/tutorial/index.html) forgoing the "Preparing your project on GitHub" and not going beyond "Checking the first build". Name your site `<USERNAME>-ftcdocs` |
| 57 | +4. To change the branch that RTD builds on do the following |
| 58 | + 1. Go to `https://readthedocs.org/dashboard/<USERNAME>-ftcdocs/advanced/` after replacing `<USERNAME>` with your username |
| 59 | + 2. Click your user in the top right corner |
| 60 | + 3. Change Default branch to the branch you want to build off of |
| 61 | +  |
| 62 | +5. Make desired changes to forked project via Github Web Editor. This is as simple as clicking edit icon after viewing any given file. Remember to follow style guide shown [here](https://docs.wpilib.org/en/stable/docs/contributing/frc-docs/style-guide.html) |
| 63 | +6. View Changes on created RTD site by visiting `https://<USERNAME>-ftcdocs.readthedocs.io/en/latest/` after replacing `<USERNAME>` with your username |
0 commit comments