rusefi
/
rusefi_documentation
mirror of https://github.com/rusefi/rusefi_documentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Documentation process refactor (#317) 

* update documentation howto

* few more changes

* try to make more readable

* try to make more readable

* add spaces for newlines

* add spaces for newlines

* add details for how to make dropdown

* change header level
This commit is contained in:
David Holdeman 2022-12-28 21:28:56 -06:00 committed by GitHub
parent 99b3240a02
commit ea0d9d85a8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 99 additions and 140 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Build-Server-and-Automation.md
View File

@ -1,6 +1,6 @@
Github Actions is currently in charge of:
* Firmware Builds: continues integration publishing at [https://rusefi.com/build_server/](https://rusefi.com/build_server/)
* Firmware Builds: continuous integration publishing at [https://rusefi.com/build_server/](https://rusefi.com/build_server/)
* Console Builds
* Simulator Builds
* Android App Builds
@ -10,7 +10,7 @@ Github Actions is currently in charge of:
* Generating Coverity code coverage pages
* Generating Doxygen documentation
* Generating iBOMs for hardware
* Uploading .ini files into rusEFI Online database using RUSEFI_ONLINE_FTP_USER
* Uploading .ini files into rusEFI Online database using RUSEFI_SSH_USER
* Generating Hardware PCB visual diffs
* Updating date stamps for builds
* Synchronizing between rusefi/rusefi/wiki to rusefi_documentation repo

38
Documentation-Strategy.md
View File

@ -1,36 +1,28 @@
# Documentation Strategy
# Side note
Open question what is in scope of rusEFI wiki and what is out of scope.
Open question: What is in scope of rusEFI wiki and what is out of scope?
* A of Nov 2022 the best cost/benefit ratio is to work on TunerStudio layout and TunerStudio field tooltips and help articles which are embedded into "Help" of specific dialogs.
* Andrey does not believe in text documentation on wiki
* Content problem versus infrastructure/structure problem like https://github.com/rusefi/rusefi_documentation/issues/250 and https://github.com/rusefi/rusefi_documentation/issues/168
* We are probably not trying to teach people how to tune HP Academy does that better
## Wiki status
# If we still hope to untangle the mess of four Wikis
As of April, 2020 the strategy is to move from MediaWiki https://rusefi.com/wiki/ to
https://github.com/rusefi/rusefi/wiki/
A full list of (Legacy) mediawiki pages is available at https://rusefi.com/wiki/index.php?title=Special:AllPages
Arguments for github:
1) Access control
2) Better change review process
3) Better history and version control management
Arguments against github
1) Weird workflow with two separate git repositories
2) Weird inconsistency of markup language between two git repositories
Arguments for mediawiki:
1) ?
As of December, 2022 the strategy is to maintain two wikis, with [the same source](https://github.com/rusefi/rusefi_documentation) for both.
[https://github.com/rusefi/rusefi/wiki/](https://github.com/rusefi/rusefi/wiki/) AKA Wiki2
[https://wiki.rusefi.com](https://wiki.rusefi.com) AKA Wiki3
Reasons for using a source repo:
1. Access control
2. Change review process
3. History and version control management
Problems with Github Wiki:
1. [Not crawlable by search engines](https://github.com/isaacs/github/issues/1683)
Problems with having two wikis:
1. Inconsistency of markup language between the two wikis
See [HOWTO Contribute to Documentation](HOWTO-contribute-to-documentation)

37
Documentation-Workflow.md
View File

@ -1,37 +0,0 @@
In order to leverage github/wiki look&feel in combination with github pull request process we have to use two git repositories in our workflow:
1) Technical git repository https://github.com/rusefi/rusefi_documentation is used to submit content using fork&pull request process
2) The user-facing https://github.com/rusefi/rusefi.wiki.git repository is displayed to viewers at https://github.com/rusefi/rusefi/wiki and Jenkins automation merges all changes from technical git into https://github.com/rusefi/rusefi.wiki.git behind the scenes.
For example, in order for user abelom to edit this page:
1) abelom would start editing at https://github.com/rusefi/rusefi_documentation/blob/master/Documentation_Workflow.md which would automatically create a branch in https://github.com/abelom/rusefi_documentation fork
2) Once changed are made, abelom would create a Pull Request
3) Once that PR is merged into primary rusEFI modified content would appear as https://github.com/rusefi/rusefi_documentation/blob/master/Documentation_Workflow.md
4) Within the next 5 minutes automation would sync this page into wiki git and it would be available with nicer layout as https://github.com/rusefi/rusefi/wiki/Documentation_Workflow
Same but in different terms:
1) Fork https://github.com/rusefi/rusefi_documentation
2) Make your changes
3) PR your changes
4) Once PR is merged by one of moderators, your changes will appear at https://github.com/rusefi/rusefi_documentation instantaneously
5) Within the next 5 minutes magic happens and the changes appear at https://github.com/rusefi/rusefi/wiki
**Q:** Is there a place where we are holding all images for these documents?
**A:** We have images in the same repository! Just add your images while editing pages. Please consider using some (any really) folder structure.
For example https://github.com/rusefi/rusefi_documentation/blob/master/FAQ/images/TunerStudio_new_project.png is visible on /wiki/ as https://raw.githubusercontent.com/wiki/rusefi/rusefi/FAQ/images/TunerStudio_new_project.png
Long story short, for images to work correctly both in the technical git and the user-facing wiki, we place all .md files into the same root folder.
(More details:
Please note that all .md files like https://github.com/rusefi/rusefi_documentation/blob/master/FAQ/HOWTO_quick_start.md are displayed without folder name like https://github.com/rusefi/rusefi/wiki/HOWTO_quick_start - which also means
that you need full image path like ``FAQ/images/rusEFI_console/rusEFI_console_start_screen.png`` for the image to be rendered properly. This is one of the github wiki features which are a bit counter-intuitive to me.
This also means that .md file names have to be unique for the whole.)
**Q:** What sort of fancy options do we have?
**A:** We can do collapsible sections & hints sections! See [cranking](Cranking) for an example.

44
Draft-of-new-Documentation-Workflow.md
View File

@ -1,44 +0,0 @@
In order to leverage the github pull request process for access control to the wiki, it is stored in a github repo:
[https://github.com/rusefi/rusefi_documentation](https://github.com/rusefi/rusefi_documentation)
When a change is made to the repo, a Github Action automatically builds the wiki and uploads it.
For example, in order for user abelom to edit this page:
1. abelom would start editing at [https://github.com/rusefi/rusefi_documentation/blob/master/Documentation_Workflow.md](https://github.com/rusefi/rusefi_documentation/blob/master/Documentation_Workflow.md) which would automatically create a branch in [https://github.com/abelom/rusefi_documentation](https://github.com/abelom/rusefi_documentation) fork
2. Once changed are made, abelom would create a Pull Request
3. Once that PR is merged into primary rusEFI modified content would appear as [https://github.com/rusefi/rusefi_documentation/blob/master/Documentation_Workflow.md](https://github.com/rusefi/rusefi_documentation/blob/master/Documentation_Workflow.md)
4. Within the next 5 minutes automation would build this page and upload it, and it would be available with nicer layout as [https://wiki.rusefi.com/Documentation_Workflow](https://wiki.rusefi.com/Documentation_Workflow)
Same but in different terms:
1. Fork [https://github.com/rusefi/rusefi_documentation](https://github.com/rusefi/rusefi_documentation)
2. Make your changes
3. PR your changes
4. Once PR is merged by one of moderators, your changes will appear at [https://github.com/rusefi/rusefi_documentation](https://github.com/rusefi/rusefi_documentation) instantaneously
5. Within the next 5 minutes magic happens and the changes appear at [https://wiki.rusefi.com](https://wiki.rusefi.com)
If you have been added to the documentation team, you will be able to make changes directly to the repo, and won't have to fork and PR.
**Q:** Is there a place where we are holding all images for these documents?
**A:** We have images in the same repository! Just add your images while editing pages. Please consider using some (any really) folder structure.
For example [https://github.com/rusefi/rusefi_documentation/blob/master/FAQ/images/TunerStudio_new_project.png](https://github.com/rusefi/rusefi_documentation/blob/master/FAQ/images/TunerStudio_new_project.png) is visible on wiki.rusefi.com as [https://wiki.rusefi.com/FAQ/images/TunerStudio_new_project.png](https://wiki.rusefi.com/FAQ/images/TunerStudio_new_project.png)
### How URLs work
Links to page names use only the name of the page; relative path does not matter.
Example:
`[The Documentation Workflow](Documentation-Workflow)`
Links to images are relative to the .md file they are in.
Example:
`![TunerStudio New Project View](FAQ/images/TunerStudio_new_project.png)`
**Q:** What sort of fancy options do we have?
**A:** We can do collapsible sections & hints sections! See [cranking](Cranking) for an example.

112
HOWTO-contribute-to-documentation.md
View File

@ -1,63 +1,111 @@
#### How to contribute to https://github.com/rusefi/rusefi_documentation
# How to contribute to documentation
Step 0: Edits are possible directly via [https://wiki.rusefi.com](https://wiki.rusefi.com/) 'Edit in GitHub' button. A Fork and PR will be created.
In order to leverage the Github pull request process for access control to the wiki, it is stored in a [Github repo](https://github.com/rusefi/rusefi_documentation).
## Editing
### Editing from a Wiki3 page
1. From the wiki page you wish to edit on [https://wiki.rusefi.com](https://wiki.rusefi.com), click on the "Edit on GitHub" link in the upper right hand corner.
2. Sign up or sign in to [Github](https://github.com) if you aren't already
3. If you have been given write access the the rusefi_documentation priority, you can commit changes directly. If not, clicking on "Propose Changes" will fork the repository and give you the option to create a pull request.
![image](https://user-images.githubusercontent.com/22799428/200407238-74b1fd66-e6b1-46cc-a7b8-398f5c5b41f6.png)
Step 1: Alternatively, sign up or sign in to https://github.com
4. Click "Create Pull Request" and wait for your change to be reviewed.
Step 2: Open https://github.com/rusefi/rusefi_documentation and click 'Fork' - this would produce your own fork/copy of rusefi_documentation which you can now edit right in your browser!
![editor](FAQ/github_online_editor.png)
### Alternative: Editing from a fork of the repo
Step 3: Edit your code and Commit changes using the button below the editor.
1. Sign up or sign in to [Github](https://github.com) if you aren't already
Step 4: Once you are ready to contribute your changes, hit 'New pull request' button on the main page of your fork.
2. Open [the documentation repo](https://github.com/rusefi/rusefi_documentation) and click 'Fork' - this would produce your own fork/copy of rusefi_documentation which you can now edit right in your browser!
![editor](FAQ/github_online_editor.png)
This would produce a [Pull request like this](https://github.com/rusefi/rusefi_documentation/pull/3) in the official rusefi repository and your changes would probably soon become public!
https://github.com/rusefi/rusefi/blob/master/firmware/tunerstudio/rusefi.input
3. Edit your code and Commit changes using the button below the editor.
4. Once you are ready to contribute your changes, click the 'New pull request' button on the main page of your fork.
#### How to contribute to rusEFI TunerStudio project
### After creating a Pull Request
Within the next 5 minutes after the pull request has been merged, a Github Action automatically builds the wiki and uploads it to both wikis.
Same as above, fork https://github.com/rusefi/rusefi and edit your local copy of
https://github.com/rusefi/rusefi/blob/master/firmware/tunerstudio/rusefi.input file
## How to contribute to rusEFI TunerStudio project
https://github.com/rusefi/rusefi/commit/9d9ae5a05499027b32ed76df3e7ee2e2e8240c31 is an example of how more help could be added
1. Sign up or sign in to [Github](https://github.com) if you aren't already
2. Go to [https://github.com/rusefi/rusefi](https://github.com/rusefi/rusefi) and click "Fork" near the upper right corner
3. Edit your fork of [the TunerStudio input](https://github.com/rusefi/rusefi/blob/master/firmware/tunerstudio/rusefi.input) file
4. Click "Contribute", then "Open Pull Request", and finally "Create Pull Request"
5. Wait for your changes to be reviewed and merged.
[This commit](https://github.com/rusefi/rusefi/commit/9d9ae5a05499027b32ed76df3e7ee2e2e8240c31) is an example of how more help could be added
right into TunerStudio project file. Lines with green background are the lines being added.
Unfortunately while you would be modifying your mainController.ini file while trying your changes, you need to edit rusefi.input file which
is a template from which rusefi.ini is generated programmatically on rusefi side.
# Wiki location migration
As of Dec 2022, https://github.com/rusefi/rusefi/wiki called "wiki2-human" is the primary documentation URL. wiki.rusefi.com migration is on-going we are fighting some issues.
# Technical implementation details
## Technical implementation details
Github Wiki is weird.
One the one hand, we have https://github.com/rusefi/rusefi_documentation called "wiki2-technical" - that's a git repository with nice pull
request process, but less nice web page rendering which start each folder by showing list of files, that's not what end users want to see.
One the one hand, we have [https://github.com/rusefi/rusefi_documentation](https://github.com/rusefi/rusefi_documentation), which we will call "wiki-source".
That's a git repository with nice pull request process, but less nice web page rendering which starts each page by showing a list of files - that's not what end users want to see.
On the other hand, we have [the Github Wiki](https://github.com/rusefi/rusefi/wiki), which we will call "wiki2" which is displayed much nicer - and that is actually implemented by ANOTHER git repository https://github.com/rusefi/rusefi.wiki.git behind the scenes.
That repository does not have a nice Pull Request process :(
On the other hand, we have https://github.com/rusefi/rusefi/wiki which is displayed much nicer - and
that https://github.com/rusefi/rusefi/wiki is actually implemented by ANOTHER git repository
https://github.com/rusefi/rusefi.wiki.git behind the scene. That https://github.com/rusefi/rusefi.wiki.git repository does not have a nice Pull Request process :(
Solution? A combination. [wiki2](https://github.com/rusefi/rusefi/wiki) and [wiki-source](https://github.com/rusefi/rusefi_documentation) repositories are actually set to mirror each other.
This way we have the nice Pull Request process on [wiki-source](https://github.com/rusefi/rusefi_documentation) and once changes are merged, the wiki-source repo is then automatically merged into the wiki2 repo, which makes actual content nicely visible on [wiki2](https://github.com/rusefi/rusefi/wiki)
Synchronization between wiki2 and wiki-source is automated via [Github Action](https://github.com/rusefi/rusefi/blob/master/.github/workflows/sync-wiki.yaml), file content is expected to be the same between these two repositories.
Solution? A combination. [wiki2-human](https://github.com/rusefi/rusefi/wiki) and [wiki2-technical](https://github.com/rusefi/rusefi_documentation) repositories are actually set to mirror each other.
This way we have the nice Pull Request process on https://github.com/rusefi/rusefi_documentation and once changes are
merged into https://github.com/rusefi/rusefi_documentation, complete https://github.com/rusefi/rusefi_documentation is automatically merged
into https://github.com/rusefi/rusefi.wiki.git which makes actual content nicely visible at https://github.com/rusefi/rusefi/wiki
Synchronization between wiki2-human and wiki2-technical is automated via [Github Action](https://github.com/rusefi/rusefi/blob/master/.github/workflows/sync-wiki.yaml), file content is expected to be the same between these two repositories.
## How Page Titles Work on Wiki3
# Technical FAQ
If the first line with content is a top-level header, e.g. `# rusEFI Documentation`, that will be used as the page title.
If not, the file name will be used as the page title, only without the hyphens.
Q: Is it ok that https://github.com/rusefi/rusefi.wiki.git cannot be opened from browser?
## How URLs work
A: There is no reason to open https://github.com/rusefi/rusefi.wiki.git from browser. Also while you technically
Links to page names use only the name of the page.
Example:
`[How to contribute to documentation](HOWTO-contribute-to-documentation)`
Result:
[How to contribute to documentation](HOWTO-contribute-to-documentation)
Links to images are relative to the root of the wiki on Wiki2, and relative to the .md file location on Wiki3.
The only way for this to work consistently between Wiki2 and Wiki3 is to have a flat directory structure.
Example:
`![TunerStudio New Project View](FAQ/images/TunerStudio_new_project.png)`
Result:
![TunerStudio New Project View](FAQ/images/TunerStudio_new_project.png)
## Technical FAQ
**Q:** Is there a place where we are holding all images for these documents?
**A:** We have images in the same repository! Just add your images while editing pages. Please consider using some (any really) folder structure.
For example [https://github.com/rusefi/rusefi_documentation/blob/master/FAQ/images/TunerStudio_new_project.png](https://github.com/rusefi/rusefi_documentation/blob/master/FAQ/images/TunerStudio_new_project.png) is visible on wiki.rusefi.com as [https://wiki.rusefi.com/FAQ/images/TunerStudio_new_project.png](https://wiki.rusefi.com/FAQ/images/TunerStudio_new_project.png)
**Q:** What sort of fancy options do we have?
**A:** We can do collapsible sections & hints sections! See [cranking](Cranking) for an example. Unfortunately, it's quite picky about how you format the markdown.
```
<details markdown="1"><summary>More...</summary>
^ Must have empty line after </summary>
# Content
</details>
^ Must have empty line after </details>
```
**Q**: Is it ok that https://github.com/rusefi/rusefi.wiki.git cannot be opened from browser?
**A**: There is no reason to open https://github.com/rusefi/rusefi.wiki.git from browser. Also while you technically
CAN "git clone https://github.com/rusefi/rusefi_documentation.wiki.git" and it would work -
you should NOT. Anyone looking to make changes should be making changes to non-wiki git via normal fork & pull request process.

2
_Sidebar.md
View File

@ -76,7 +76,7 @@
# Contributors
- [Documentation Strategy](Documentation-Strategy)
- [Documentation Workflow](Documentation-Workflow)
- [HOWTO Contribute to Documentation](HOWTO-contribute-to-documentation)
- [Firmware Code Doxygen](https://rusefi.com/docs/html)
- [Firmware Code Automated Test Coverage](https://rusefi.com/docs/unit_tests_coverage)
- [HOWTO Contribute To Firmware](HOWTO-contribute-to-firmware)

2
mkdocs/mkdocs.yaml
View File

@ -74,7 +74,7 @@ nav:
- 'Creating a PnP PCB': HOWTO-Make-a-PnP-board
- 'Contributors':
- 'Documentation Strategy': Documentation-Strategy
- 'Documentation Workflow': Documentation-Workflow
- 'HOWTO Contribute to Documentation': HOWTO-contribute-to-documentation
- 'Firmware Code Doxygen': "https://rusefi.com/docs/html"
- 'Firmware Code Automated Test Coverage': "https://rusefi.com/docs/unit_tests_coverage"
- 'HOWTO Contribute To Firmware': HOWTO-contribute-to-firmware