Skip to content

FlyByWire Documentation Guide

- Documentation Project GitHub

Background

Guides

If you would like to setup the documentation project locally please continue with this guide.

If you would like to understand our guidelines on writing and different available features please see the Writing Documentation Page instead.

The FlyByWire Documentation Project aims to provide all necessary information and documentation to successfully install and use the FlyByWire A32NX aircraft in Microsoft Flight Simulator.

For this, we provide documentation about the A32NX add-on itself, but also valuable additional documentation on how to fly an airliner on Microsoft Flight Simulator in general and even some specific A320neo documentation for the more involved user.

We apply very high standards to the quality and accuracy of our documentation so that it is easy to read and understand but also as correct as possible. Therefore, we have a strict quality process and everything is reviewed by several users and real pilots from our team.

How to Contribute

Contacts for FlyByWire Documentation Team

If you have questions or suggestions, or if you want to contribute to the FlyByWire Documentation project, please contact us on Discord:

- Discord Link

  • valastiri
  • cdr_maverick
  • slein15

Required Tools

To participate in the FlyByWire Documentation Project, you need to have the following tools installed:

  • GitHub account and Git (GitHub Quickstart)
  • Python (Python Downloads)
  • Install the following Python-based tools (see install command below):
    • MkDocs (MkDocs)
    • mkdocs-awesome-pages-plugin
    • mkdocs-git-revision-date-localized-plugin
    • mkdocs-redirects
    • mkdocs-embed-external-markdown
    • mkdocs-video
    • mike
    • pillow
    • cairosvg

  • Create and activate a Python Virtual Environment (virtualenv) to be used for working on the documentation project:

    Run In Terminal
    python -m venv venv

    Once created, you need to activate it. Use the following command on Windows:

    Activating virtualenv on Windows
    .\venv\Scripts\activate.bat
    Or the following command on Linux and macOS:
    Activating virtualenv on Linux and macOS
    source venv/bin/activate
    - Install dependencies with this single line command:
    Run In Terminal
    pip install -r requirements.txt

Using virtualenv

Starting with Python 3.11, the pip tool will fail to install dependencies and packages globally, instead it's recommended to use virtualenv. If you desire to install packages globally, you must use another tool, such as pipx. We recommend using virtualenv because it's easier and the recommended way to work on Python projects.

Activating virtualenv

It's important to note that virtualenv activation is not persisted. If you restart your terminal/command prompt and want to preview your work on the documentation project again, you have to reactivate your virutalenv using the appropriate activation command that was shown earlier in this guide.

Pillow + Cairo Dependency

As part of the new social card feature released with mkdocs-material 8.5.0 Pillow and Cairo Graphics dependencies were added. We bundle this as part of our requirements.txt to ensure the dependencies are installed when attempting to test social cards locally. If you encounter any issues with these python packages:

  • Install GTK+ for Windows.

For more information, including other operating systems, refer to the Social Card Dependencies Section on the mkdocs-material documentation.

Social Cards Feature

Important Information

For general purposes, you do not need to test or utilize this feature locally unless you want to develop or change configurations related to this feature. Please be aware of the information below if you intend to test this locally.

We have added the social cards feature to the FBW documentation project. When generating the social cards locally, the directory .cache is created where all the assets are generated. See Complete Local Builds.

You may need to manually clean any files within the .cache directory if you encounter any build issues after generating / modifying configuration files related to this feature.

Process

Preview your Local Clone

  • Fork the - Documentation Project GitHub (How to fork a repository).
  • Create a local clone (How to clone your forked repository).
  • Checkout the "primary" branch - this is the main branch of the current FlyByWire Documentation Project.

  • In a command line terminal, go to the cloned repository folder and start mkdocs.exe serve to start the local preview server.

    This should look like this:

    > mkdocs.exe serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 4.03 seconds
INFO     -  [12:05:30] Serving on http://127.0.0.1:8000/

    Building the Project with No Internet Connection

    This project utilizes the external-markdown plugin, which pulls MarkDown files from other repositories during the build for both production and development. This helps reference other important documentation externally without having to copy and paste it into this project.

    When working on a feature branch without an internet connection, your development server may exit and fail to build, resulting in:

    Error! https://[hyperlink here] returned connection error

    To bypass this issue, you can comment out the external-markdown plugin temporarily in mkdocs.yml found in the /root of this project. (Please ensure not to commit this change when creating a Pull Request.) See the example below:

    mkdocs.yml example configured for offline builds
    # Plugins
plugins:
search:
  lang: en
# Comment out the plugin below if building docs without an internet connection.
# external-markdown: {} (1)
    1. For production or PR purposes, please ensure that the above plugin reads external-markdown: {} (without the preceding #) before finalizing your PR.

Faster Preview Server

You can opt to use a faster instance of the developer server by invoking the flag --dirty. This just checks for any markdown that has changed since the HTML was rendered and will reconstruct any relevant pages only, rather than rebuilding the entire website.

mkdocs.exe serve --dirty

Navigation and new internal links may not get updated on other pages while using --dirty. Verify links using the standard serve or build command.

  • You can now browse the current checked out branch in a browser at this address: http://127.0.0.1:8000/. The site renders every time you save any filename.md you are working on.

  • Optional: Build a static site locally for testing:

    mkdocs build --clean --no-directory-urls
    • The site will be built locally under /site on in your local repo for user testing. Openindex.html in the root of /site to preview.
    • Note: --no-directory-urls allows usage of reference links when browsing the locally built site. Prevents having to find each index.html related to every filename.md to preview the relevant page.

Make Changes or Additions to the Documentation

  • Create a new branch based on branch "primary" (might differ for certain subprojects) and checkout this new branch. Give a short but meaningful name to the branch.
  • Make initial changes to your local branch.
  • Create a Draft Pull Request (aka PR) early to let people know what you are working on.
    • Explain in the PR Description what you are changing/adding and how people should review your changes.
  • Work on your changes locally, preview constantly and push your changes regularly to get a preview deployment for others to provide feedback.
    • Every time you push changes to your PR, a preview is generated with a URL. You can share this link in Discord for the team to provide feedback easily. The URL (by the Vercel bot) is visible as a comment on your PR GitHub page.
  • When finished, push your final changes to the PR, update the PR description if required and mark it "Ready for Review".
  • Someone from the documentation team will review your changes, provide feedback, potentially ask for changes, and eventually approve and merge your changes.

Adding Plugins or Markdown Extensions

Please use the alternative "key/value" pairs method when adding plugins or markdown extensions, with special note that an empty value must be provided when no options are defined.

Sample New Config
plugins:
  search: {}
  awesome-pages: {}
Old Config
plugins:
    - search
    - awesome-pages

Build Pipeline and Config Changes

To facilitate smooth local development, we have made some changes between production builds and local development.

Building for production now uses the production.yml file, which deep merges with mkdocs.yml using the INHERIT function with MkDocs.

mkdocs build --config-file production.yml

Complete Local Builds

You can still follow the instructions to preview your local clone to test and preview your changes locally.

If you would like to fully test a complete build of the production website, you need to run the following:

  • mkdocs.exe serve --config-file production.yml
  • mkdocs.exe build --clean --no-directory-urls --config-file production.yml

Additional Plugins in production.yml

The following plugins are included:

  • Social Cards

Ideas and Issues

Please use GitHub's Issue tracker for any documentation request or issues you might have encountered.

- Documentation Project Issues