diff --git a/docs/dev-corner/dev-guide/.pages b/docs/dev-corner/dev-guide/.pages index 20afbdf65..7a0c022a6 100644 --- a/docs/dev-corner/dev-guide/.pages +++ b/docs/dev-corner/dev-guide/.pages @@ -4,4 +4,5 @@ nav: - Resources: resources.md - Setup Dev Environment: setup-environment.md - Contribution Guidelines: contribute.md + - a32nx-repo-docs - Specific Topics: specific 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..19f027db3 --- /dev/null +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/.pages @@ -0,0 +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 + - ... 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..1bdc2afa1 --- /dev/null +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-events.md @@ -0,0 +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 new file mode 100644 index 000000000..3be82c4b6 --- /dev/null +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/a320-simvars.md @@ -0,0 +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 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..397392716 --- /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 are 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/a32nx-repo-docs/systems-guidelines.md b/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md new file mode 100644 index 000000000..7204aa35b --- /dev/null +++ b/docs/dev-corner/dev-guide/a32nx-repo-docs/systems-guidelines.md @@ -0,0 +1,52 @@ +# 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. + +# General + +{{ external_markdown('https://raw.githubusercontent.com/flybywiresim/a32nx/master/src/systems/guidelines.md', '# General') }} + +## 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!`') }} + +{{ 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 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 diff --git a/docs/dev-corner/dev-guide/index.md b/docs/dev-corner/dev-guide/index.md index 305874dbb..1d41c0e6a 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 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. | 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