From 630c440197c2e7f844312ca65161d7984557ecf4 Mon Sep 17 00:00:00 2001 From: Valastiri Date: Tue, 19 Apr 2022 06:02:39 +0800 Subject: [PATCH 01/10] create sample external markdown from a32nx repo --- docs/dev-corner/dev-guide/a32nx-repo-docs/a320-events.md | 1 + docs/dev-corner/dev-guide/a32nx-repo-docs/a320-simvars.md | 1 + 2 files changed, 2 insertions(+) create mode 100644 docs/dev-corner/dev-guide/a32nx-repo-docs/a320-events.md create mode 100644 docs/dev-corner/dev-guide/a32nx-repo-docs/a320-simvars.md diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-events.md b/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-events.md new file mode 100644 index 000000000..cfbce97bf --- /dev/null +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-events.md @@ -0,0 +1 @@ +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/docs/a320-events.md', '') }} \ No newline at end of file diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-simvars.md b/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-simvars.md new file mode 100644 index 000000000..016998445 --- /dev/null +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-simvars.md @@ -0,0 +1 @@ +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/docs/a320-simvars.md', '') }} \ No newline at end of file From b437c1bbfe4e0ad4e41630dbd27fca1c871d9e85 Mon Sep 17 00:00:00 2001 From: Valastiri Date: Tue, 19 Apr 2022 06:02:47 +0800 Subject: [PATCH 02/10] add pages to navigation --- docs/dev-corner/dev-guide/.pages | 1 + docs/dev-corner/dev-guide/a32nx-repo-docs/.pages | 4 ++++ 2 files changed, 5 insertions(+) create mode 100644 docs/dev-corner/dev-guide/a32nx-repo-docs/.pages diff --git a/docs/dev-corner/dev-guide/.pages b/docs/dev-corner/dev-guide/.pages index 20afbdf65..3ac4dbac9 100644 --- a/docs/dev-corner/dev-guide/.pages +++ b/docs/dev-corner/dev-guide/.pages @@ -5,3 +5,4 @@ nav: - Setup Dev Environment: setup-environment.md - Contribution Guidelines: contribute.md - Specific Topics: specific + - A32NX Repo Docs: a32nx-repo-docs diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/.pages b/docs/dev-corner/dev-guide/a32nx-repo-docs/.pages new file mode 100644 index 000000000..fedbe6aaa --- /dev/null +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/.pages @@ -0,0 +1,4 @@ +title: A32NX Repository Documentation +nav: + - A320neo Custom Events: a320-events.md + - A320neo Local SimVars: a320-simvars.md From 74376c40521847b2a767494ef358adf492930f7e Mon Sep 17 00:00:00 2001 From: Valastiri Date: Tue, 19 Apr 2022 06:08:40 +0800 Subject: [PATCH 03/10] change navigation style to automatic --- docs/dev-corner/dev-guide/a32nx-repo-docs/.pages | 3 +-- docs/dev-corner/dev-guide/a32nx-repo-docs/a320-events.md | 4 ++++ docs/dev-corner/dev-guide/a32nx-repo-docs/a320-simvars.md | 4 ++++ 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/.pages b/docs/dev-corner/dev-guide/a32nx-repo-docs/.pages index fedbe6aaa..533e09b3e 100644 --- a/docs/dev-corner/dev-guide/a32nx-repo-docs/.pages +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/.pages @@ -1,4 +1,3 @@ title: A32NX Repository Documentation nav: - - A320neo Custom Events: a320-events.md - - A320neo Local SimVars: a320-simvars.md + - ... diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-events.md b/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-events.md index cfbce97bf..1bdc2afa1 100644 --- a/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-events.md +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-events.md @@ -1 +1,5 @@ +# A320neo Custom Events + +This page is pulled externally from the A32NX repository. + {{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/docs/a320-events.md', '') }} \ No newline at end of file diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-simvars.md b/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-simvars.md index 016998445..3be82c4b6 100644 --- a/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-simvars.md +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-simvars.md @@ -1 +1,5 @@ +# A320neo Local SimVars + +This page is pulled externally from the A32NX repository. + {{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/docs/a320-simvars.md', '') }} \ No newline at end of file From 91d189f5136ecf26281a3b4ad2f70ff836ce2cc2 Mon Sep 17 00:00:00 2001 From: Valastiri Date: Tue, 19 Apr 2022 09:00:13 +0800 Subject: [PATCH 04/10] change lvars-events.md links to internal docs links --- docs/fbw-a32nx/a32nx-api/lvars-events.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fbw-a32nx/a32nx-api/lvars-events.md b/docs/fbw-a32nx/a32nx-api/lvars-events.md index d0bf82011..79c231168 100644 --- a/docs/fbw-a32nx/a32nx-api/lvars-events.md +++ b/docs/fbw-a32nx/a32nx-api/lvars-events.md @@ -6,8 +6,8 @@ In addition to the above documentation all custom variables and custom events ar ## Docs: -- [Custom LVARs](https://github.com/flybywiresim/a32nx/blob/master/docs/a320-simvars.md){target=new} -- [Custom Events](https://github.com/flybywiresim/a32nx/blob/master/docs/a320-events.md){target=new} +- [Custom LVARs](../../dev-corner/dev-guide/a32nx-repo-docs/a320-simvars.md){target=new} +- [Custom Events](../../dev-corner/dev-guide/a32nx-repo-docs/a320-events.md){target=new} ## Templates From 4eaf02ffe7a6ef6f4c81e08fdad1940670d42928 Mon Sep 17 00:00:00 2001 From: Valastiri Date: Fri, 22 Apr 2022 04:55:02 +0800 Subject: [PATCH 05/10] update navigation in dev-corner --- docs/dev-corner/dev-guide/.pages | 2 +- docs/dev-corner/dev-guide/a32nx-repo-docs/.pages | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/dev-corner/dev-guide/.pages b/docs/dev-corner/dev-guide/.pages index 3ac4dbac9..7a0c022a6 100644 --- a/docs/dev-corner/dev-guide/.pages +++ b/docs/dev-corner/dev-guide/.pages @@ -4,5 +4,5 @@ nav: - Resources: resources.md - Setup Dev Environment: setup-environment.md - Contribution Guidelines: contribute.md + - a32nx-repo-docs - Specific Topics: specific - - A32NX Repo Docs: a32nx-repo-docs diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/.pages b/docs/dev-corner/dev-guide/a32nx-repo-docs/.pages index 533e09b3e..19f027db3 100644 --- a/docs/dev-corner/dev-guide/a32nx-repo-docs/.pages +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/.pages @@ -1,3 +1,8 @@ title: A32NX Repository Documentation nav: + - Overview: index.md + - Systems: systems.md + - Systems Guidelines: systems-guidelines.md + - Custom Events: a320-events.md + - SimVars: a320-simvars.md - ... From 2c16038400231be5c12692dc43e1751dbfbdcd14 Mon Sep 17 00:00:00 2001 From: Valastiri Date: Fri, 22 Apr 2022 04:55:27 +0800 Subject: [PATCH 06/10] update various overview pages --- .../dev-corner/dev-guide/a32nx-repo-docs/index.md | 15 +++++++++++++++ docs/dev-corner/dev-guide/index.md | 13 +++++++------ 2 files changed, 22 insertions(+), 6 deletions(-) create mode 100644 docs/dev-corner/dev-guide/a32nx-repo-docs/index.md diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/index.md b/docs/dev-corner/dev-guide/a32nx-repo-docs/index.md new file mode 100644 index 000000000..7b226e594 --- /dev/null +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/index.md @@ -0,0 +1,15 @@ + + +# Overview + +This section contains A32NX specific documentation from the [A32NX GitHub Repository](https://github.com/flybywiresim/a32nx). All pages found on this +section is pulled externally to be rendered on this site during the build process. + +| Topics | +|:-------------------------------------------:| +| [Systems](systems.md) | +| [Systems Guidelines](systems-guidelines.md) | +| [Custom Events](a320-events.md) | +| [SimVars](a320-simvars.md) | + + diff --git a/docs/dev-corner/dev-guide/index.md b/docs/dev-corner/dev-guide/index.md index 305874dbb..fa5b6dc43 100644 --- a/docs/dev-corner/dev-guide/index.md +++ b/docs/dev-corner/dev-guide/index.md @@ -18,10 +18,11 @@ It is structured in a series of sections which are based on each other starting ## Topics -| Quick Links | Description | -| :---- | :---- | -| [Resources](resources.md) | General information and documentation resources | -| [Setting up Development Environment](setup-environment.md) | From software to troubleshooting everything you need to successfully change and compile the code. | -| [Contribution Guidelines](contribute.md) | From General Development Process and Practices to Pull Requests - everything you need to know to collaborate and contribute to the project. | -| [Specific Development Areas](specific/) | Information for specific parts of the project like the flyPad or avionics. | +| Quick Links | Description | +|:-----------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------| +| [Resources](resources.md) | General information and documentation resources | +| [Setting up Development Environment](setup-environment.md) | From software to troubleshooting everything you need to successfully change and compile the code. | +| [Contribution Guidelines](contribute.md) | From General Development Process and Practices to Pull Requests - everything you need to know to collaborate and contribute to the project. | +| [A32NX Repository Documentation](a32nx-repo-docs/) | This section contains A32NX specific documentation from various locations in the [A32NX GitHub Repository](https://github.com/flybywiresim/a32nx). | +| [Specific Development Areas](specific/) | Information for specific parts of the project like the flyPad or avionics. | From d4908f97d31d92ae618655dff7994fa810362da3 Mon Sep 17 00:00:00 2001 From: Valastiri Date: Fri, 22 Apr 2022 04:55:38 +0800 Subject: [PATCH 07/10] add systems and systems-guidelines documentation --- .../dev-guide/a32nx-repo-docs/systems-guidelines.md | 8 ++++++++ docs/dev-corner/dev-guide/a32nx-repo-docs/systems.md | 8 ++++++++ 2 files changed, 16 insertions(+) create mode 100644 docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md create mode 100644 docs/dev-corner/dev-guide/a32nx-repo-docs/systems.md diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md b/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md new file mode 100644 index 000000000..6aa646dd2 --- /dev/null +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md @@ -0,0 +1,8 @@ +# A32NX Systems Guidelines + +This page is pulled externally from the A32NX repository. + +Please read through the guidelines described in this document. These guidelines are based upon pull request review comments. When reviewing pull requests, feel free to extend +this document rather than repeating the same comment on pull requests over and over again. + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '') }} \ No newline at end of file diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/systems.md b/docs/dev-corner/dev-guide/a32nx-repo-docs/systems.md new file mode 100644 index 000000000..d78764695 --- /dev/null +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/systems.md @@ -0,0 +1,8 @@ +# A32NX Systems + +This page is pulled externally from the A32NX repository. + +The `systems/` folder contains code for simulating Airbus aircraft systems. Please read through the [guidelines](systems-guidelines.md) and keep yourself up to date with those +guidelines as they might change over time. We also highly recommend reading through this document to get an overview of the software design. + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/README.md', '') }} \ No newline at end of file From 64cb937e699c87933fbcf06528daf2840e975b99 Mon Sep 17 00:00:00 2001 From: Valastiri Date: Sun, 24 Apr 2022 00:16:43 +0800 Subject: [PATCH 08/10] grammar corrections + copy changes --- docs/dev-corner/dev-guide/a32nx-repo-docs/index.md | 2 +- docs/dev-corner/dev-guide/index.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/index.md b/docs/dev-corner/dev-guide/a32nx-repo-docs/index.md index 7b226e594..397392716 100644 --- a/docs/dev-corner/dev-guide/a32nx-repo-docs/index.md +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/index.md @@ -3,7 +3,7 @@ # Overview This section contains A32NX specific documentation from the [A32NX GitHub Repository](https://github.com/flybywiresim/a32nx). All pages found on this -section is pulled externally to be rendered on this site during the build process. +section are pulled externally to be rendered on this site during the build process. | Topics | |:-------------------------------------------:| diff --git a/docs/dev-corner/dev-guide/index.md b/docs/dev-corner/dev-guide/index.md index fa5b6dc43..1d41c0e6a 100644 --- a/docs/dev-corner/dev-guide/index.md +++ b/docs/dev-corner/dev-guide/index.md @@ -18,11 +18,11 @@ It is structured in a series of sections which are based on each other starting ## Topics -| Quick Links | Description | -|:-----------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------| -| [Resources](resources.md) | General information and documentation resources | -| [Setting up Development Environment](setup-environment.md) | From software to troubleshooting everything you need to successfully change and compile the code. | -| [Contribution Guidelines](contribute.md) | From General Development Process and Practices to Pull Requests - everything you need to know to collaborate and contribute to the project. | -| [A32NX Repository Documentation](a32nx-repo-docs/) | This section contains A32NX specific documentation from various locations in the [A32NX GitHub Repository](https://github.com/flybywiresim/a32nx). | -| [Specific Development Areas](specific/) | Information for specific parts of the project like the flyPad or avionics. | +| Quick Links | Description | +|:-----------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Resources](resources.md) | General information and documentation resources | +| [Setting up Development Environment](setup-environment.md) | From software to troubleshooting everything you need to successfully change and compile the code. | +| [Contribution Guidelines](contribute.md) | From General Development Process and Practices to Pull Requests - everything you need to know to collaborate and contribute to the project. | +| [A32NX Repository Documentation](a32nx-repo-docs/) | This section contains A32NX specific developer documentation from various locations in the [A32NX GitHub Repository](https://github.com/flybywiresim/a32nx). | +| [Specific Development Areas](specific/) | Information for specific parts of the project like the flyPad or avionics. | From 06d2d71e89ef09829ba83b570b2bf647d253a1f9 Mon Sep 17 00:00:00 2001 From: Valastiri Date: Mon, 25 Apr 2022 04:44:20 +0800 Subject: [PATCH 09/10] testing manual input --- .../dev-guide/a32nx-repo-docs/systems-guidelines.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md b/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md index 6aa646dd2..77f720121 100644 --- a/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md @@ -5,4 +5,12 @@ This page is pulled externally from the A32NX repository. Please read through the guidelines described in this document. These guidelines are based upon pull request review comments. When reviewing pull requests, feel free to extend this document rather than repeating the same comment on pull requests over and over again. -{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '') }} \ No newline at end of file +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Clippy') }} + +## Code + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '# Code') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Testing') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## `assert_eq!` and `assert_ne!`') }} \ No newline at end of file From e2c5c6e1b18b72132ad0464551d74f2f2390541d Mon Sep 17 00:00:00 2001 From: Valastiri Date: Tue, 26 Apr 2022 18:17:49 +0800 Subject: [PATCH 10/10] overhaul systems-guidelines.md page to satisfy strict validation --- .../a32nx-repo-docs/systems-guidelines.md | 44 +++++++++++++++++-- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md b/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md index 77f720121..7204aa35b 100644 --- a/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md @@ -5,12 +5,48 @@ This page is pulled externally from the A32NX repository. Please read through the guidelines described in this document. These guidelines are based upon pull request review comments. When reviewing pull requests, feel free to extend this document rather than repeating the same comment on pull requests over and over again. -{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Clippy') }} +# General -## Code +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '# General') }} -{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '# Code') }} +## Units of measurement + +We use the [`uom`](https://crates.io/crates/uom) crate to provide us with units of measurement types. Whenever possible use these types instead of numeric types. + +**Rationale:** Reduces the risk of computational errors such as mistaking a value in pounds with a value in kilograms. Using these types also reduces the risk of passing function arguments in the wrong order. + +When reading and writing `uom` types using `SimulatorReader` and `SimulatorWriter`, don't convert to a specific unit unless the unit deviates from the default unit defined in [`systems/src/simulation/mod.rs`](https://github.com/flybywiresim/a32nx/blob/master/src/systems/systems/src/simulation/mod.rs). + +**Rationale**: This leads to shorter and easier to read code. The default unit works for the majority of cases. + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## HashMap and HashSet') }} {{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Testing') }} -{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## `assert_eq!` and `assert_ne!`') }} \ No newline at end of file +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## `assert_eq!` and `assert_ne!`') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Law of Demeter') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Explicit `match` pattern declaration') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Implicit Enum variant value') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Prefer monomorphisation') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Passing data around') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Do not re-read SimVars written by Rust code') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Avoid repeating trait `where` clauses') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Avoid copying default trait function implementations') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Avoid `extern crate` usage') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Limit item visibility') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Avoid dependencies between child modules') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '## Single assignment for simple `if else`') }} + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '# Style') }} \ No newline at end of file