Merge pull request #171 from fast-aircraft-design/doc-rework

Doc rework

README.md

@@ -0,0 +1,44 @@
+![Tests](https://github.com/fast-aircraft-design/FAST-OAD/workflows/Tests/badge.svg)
+[![Documentation Status](https://readthedocs.org/projects/fast-oad/badge/?version=latest)](https://fast-oad.readthedocs.io/en/latest/?badge=latest)
+
+FAST-OAD: Future Aircraft Sizing Tool - Overall Aircraft Design
+===============================================================
+
+FAST-OAD is a framework for performing rapid Overall Aircraft Design.
+
+It proposes multi-disciplinary analysis and optimisation by relying on
+the [OpenMDAO framework](https://openmdao.org/).
+
+FAST-OAD allows easy switching between models for a same discipline, and
+also adding/removing disciplines to match the need of your study.
+
+Currently, FAST-OAD is bundled with models for commercial transport
+aircraft of years 1990-2000. Other models will come and you may create
+your own models and use them instead of bundled ones.
+
+More details can be found in the [official
+documentation](https://fast-aircraft-design.github.io/FAST-OAD-doc/).
+
+Install
+-------
+
+**Prerequisite**:FAST-OAD needs at least **Python 3.6.1** (usage of
+**Python 3.8.**\* is discouraged as Jupyter notebooks are still [not
+compatible with
+it](https://github.com/jupyterlab/jupyterlab/issues/6487)).
+
+It is recommended (but not required) to install FAST-OAD in a virtual
+environment ([conda](https://docs.conda.io/en/latest/),
+[venv](https://docs.python.org/3.7/library/venv.html), ...)
+
+Once Python is installed, FAST-OAD can be installed using pip.
+
+> **Note**: If your network uses a proxy, you may have to do [some
+> settings](https://pip.pypa.io/en/stable/user_guide/#using-a-proxy-server)
+> for pip to work correctly
+
+You can install the latest version with this command:
+
+``` {.bash}
+$ pip install --upgrade FAST-OAD
+```

README.rst

@@ -24,26 +24,9 @@ Once Python is installed, FAST-OAD can be installed using pip.
 
     **Note**: If your network uses a proxy, you may have to do `some settings <https://pip.pypa.io/en/stable/user_guide/#using-a-proxy-server>`_ for pip to work correctly
 
-Until FAST-OAD is publicly released, the installation process must rely on GitHub
-instead of PyPI. Therefore, you have 2 ways to install it:
-
-With Git installed
-==================
 You can install the latest version with this command:
 
 .. code:: bash
 
-    $ pip install -e git+https://github.com/fast-aircraft-design/FAST-OAD.git
-
-At the prompt, enter your GitHub credentials.
-
-Without Git installed
-=====================
-Please download this tarball: `<https://github.com/fast-aircraft-design/FAST-OAD/archive/master.zip>`_
-
-Unzip it in the location of your choice, then do:
-
-.. code:: bash
-
-   $ pip install -e <location/of/FAST-OAD-latest/>
+    $ pip install --upgrade FAST-OAD
 

docs/documentation/index.rst

@@ -8,6 +8,7 @@ Here you will find the first things to know about FAST-OAD.
    :maxdepth: 2
 
    Installation <install>
+   Process overview <overview>
    Usage <usage>
    Process variables <variables>
    How to add your modules <add_modules>

docs/documentation/install.rst

@@ -11,28 +11,8 @@ Once Python is installed, FAST-OAD can be installed using pip.
 
     **Note**: If your network uses a proxy, you may have to do `some settings <https://pip.pypa.io/en/stable/user_guide/#using-a-proxy-server>`_ for pip to work correctly
 
-Until FAST-OAD is publicly released, the installation process must rely on GitHub
-instead of PyPI. Therefore, you have 2 ways to install it:
-
-******************
-With Git installed
-******************
-You can install the latest version with this command:
-
-.. code:: bash
-
-    $ pip install -e git+https://github.com/fast-aircraft-design/FAST-OAD.git
-
-At the prompt, enter your GitHub credentials.
-
-*********************
-Without Git installed
-*********************
-Please download this tarball: `<https://github.com/fast-aircraft-design/FAST-OAD/archive/master.zip>`_
-
-Unzip it in the location of your choice, then do:
+IpYou can install the latest version with this command:
 
 .. code:: bash
 
-   $ pip install -e <location/of/FAST-OAD-latest/>
-
+    $ pip install --upgrade FAST-OAD

docs/documentation/overview.rst

@@ -0,0 +1,69 @@
+.. _usage:
+
+#################
+FAST-OAD overview
+#################
+
+FAST-OAD is a framework for performing rapid Overall Aircraft Design.
+
+It proposes multi-disciplinary analysis and optimisation by relying on the
+`OpenMDAO framework <https://openmdao.org/>`_.
+
+FAST-OAD allows easy switching between models for a same discipline, and also adding/removing
+disciplines to match the need of your study.
+
+Currently, FAST-OAD is bundled with models for commercial transport aircraft of years 1990-2000.
+Other models will come and you may create your own models and use them instead of bundled ones.
+
+************
+How it works
+************
+
+A FAST-OAD run wraps up an OpenMDAO problem, which is, in a nutshell, the assembly of components
+that each have input and output variables. Of course, the outputs of some component can be the
+inputs of some other ones, so that the whole system can be solved.
+
+FAST-OAD allows to define the problem to solve (or to optimize) through a configuration file that
+makes easy to add/remove/replace any component. By doing that, the input data of the problem can
+be very different from one problem to the other, but FAST-OAD comes with facilities to build the
+needed input data files.
+
+A FAST-OAD problem can be fully run from :ref:`command line interface<usage-cli>`
+or from the Python API.
+
+Usage of Python API, including pre-processing and post-processing utilities are
+currently provided through :ref:`Python notebooks<python-usage>`.
+
+**************************
+Overview of FAST-OAD files
+**************************
+A typical run of FAST-OAD uses two types of user files:
+
+configuration file (**.toml**)
+==============================
+
+This file defines the OpenMDAO problem by defining :
+
+    - what components will be in the problem
+    - the files for input and output data
+    - the problem settings
+    - the definition of the optimization problem if needed
+
+A detailed description of this file can be found :ref:`here<configuration-file>`.
+
+
+The input and output data files (**.xml**)
+==========================================
+
+These files contain the information of the variables involved in the
+system model:
+
+#. The input file contains the global inputs values
+   required to run all the model. The user is free to modify the values
+   of the variables in order that these new values are considered during
+   a model run.
+#. The output file contains all the variables (inputs +
+   outputs) values obtained after a model run.
+
+The content of these files and the way variables are named and serialized is
+described :ref:`here<variables>`.

docs/documentation/usage.rst

@@ -11,6 +11,8 @@ OpenMDAO systems. This part is addressed in the :ref:`API documentation<fastoad>
 
 .. contents::
 
+.. _configuration-file:
+
 *******************************
 The FAST-OAD configuration file
 *******************************
@@ -215,6 +217,9 @@ This section can be repeated several times to add as many constraint variables a
 
 Also, see :ref:`get-variable-list`.
 
+
+.. _usage-cli:
+
 ***********************************
 Using FAST-OAD through Command line
 ***********************************