New structure of project documentation

Signed-off-by: Robert Winkler <rwinkler@antmicro.com>

docs/architecture/index.rst

@@ -0,0 +1,16 @@
+============================
+Xilinx 7-series Architecture
+============================
+
+.. toctree::
+   :maxdepth: 1
+
+   overview
+   configuration
+   bitstream_format
+   interconnect
+   dram_configuration
+   glossary
+   reference
+   code_of_conduct
+   updating_the_docs

docs/db_dev_process/index.rst

@@ -0,0 +1,13 @@
+============================
+Database Development Process
+============================
+
+.. toctree::
+   :maxdepth: 1
+
+   readme
+   contributing
+   fuzzers/index
+   minitests/index
+   parts
+

docs/format/index.rst

@@ -0,0 +1,8 @@
+============
+Output Files
+============
+
+.. toctree::
+
+   db
+   tile.rst

docs/getting.rst

@@ -0,0 +1,6 @@
+===============
+Getting Started
+===============
+
+.. toctree::
+   db_dev_process/readme

docs/index.rst

@@ -1,10 +1,6 @@
-.. Project X-Ray documentation master file, created by
+=============
-   sphinx-quickstart on Mon Feb  5 11:04:37 2018.
+Project X-Ray
-   You can adapt this file completely to your liking, but it should at least
+=============
-   contain the root `toctree` directive.
-
-Welcome to Project X-Ray
-=========================================
 
 `Project X-Ray`_ documents the `Xilinx`_ 7-Series FPGA architecture to enable
 development of open-source tools.  Our goal is to provide sufficient information
@@ -15,31 +11,30 @@ to develop a free and open Verilog to bitstream toolchain for these devices.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Xilinx 7-series Architecture
+   :caption: Introduction
 
-   architecture/overview
+   introduction
-   architecture/configuration
+
-   architecture/bitstream_format
+.. toctree::
-   architecture/interconnect
+   :maxdepth: 2
-   architecture/dram_configuration
+   :caption: Getting Started
-   architecture/glossary
+
-   architecture/reference
+   getting
-   architecture/code_of_conduct
+
-   architecture/updating_the_docs
+.. toctree::
+   :maxdepth: 2
+   :caption: Xilinx 7-Series Architecture
+
+   architecture/index
 
 .. toctree::
    :maxdepth: 2
    :caption: Database Development Process
 
-   db_dev_process/readme
+   db_dev_process/index
-   db_dev_process/contributing
-   db_dev_process/fuzzers/index
-   db_dev_process/minitests/index
-   db_dev_process/parts
 
 .. toctree::
    :maxdepth: 2
-   :caption: Output File Formats
+   :caption: Output Formats
 
-   format/db
+   format/index
-   format/tile

docs/introduction.rst

@@ -0,0 +1,67 @@
+============
+Introduction
+============
+
+`Project X-Ray`_ documents the `Xilinx`_ 7-Series FPGA architecture to enable
+the development of open-source tools.  Our goal is to provide sufficient information
+to develop a free and open Verilog to bitstream toolchain for these devices.
+
+The project is a part of SymbiFlow Toolchain. `SymbiFlow`_ uses the obtained
+information about the chip in `Architecture Definitions`_ project, which
+allows for creating bitstreams for many architectures including 7-Series devices.
+
+Collected information
+---------------------
+
+To allow the usage of Xilinx FPGAs in SymbiFlow toolchain we collect some
+important data about the Xilinx chips. The needed information includes:
+
+   - Architecture description:
+
+      * chip internals
+      * timings
+
+   - Bitstream format:
+
+      * metadata (i.e. header, crc)
+      * configuration bits
+
+Final results are stored in the database which is further used by the
+`Architecture Definitions`_ project. The whole database is described in
+the dedicated :doc:`chapter <format/index>`.
+
+Methodology
+-----------
+
+The most important element of the project are fuzzers - scripts responsible
+for obtaining information about the chips. Their name comes from the fact that
+they use a similar idea to `Fuzz testing`_. Firstly, they generate a huge
+amount of designs in which the examined chip property is either enabled or
+disabled. By comparing the differences in the final bitstream obtained
+from vendor tools, we can detect relations between bits in the bitstream and
+provided functionalities.
+
+However, some of the fuzzers works differently, i.e. they just creating
+the database structure, the whole idea is similar and rely on the output produced
+by the vendor tools.
+
+All fuzzers are described in the dedicated :doc:`chapter <db_dev_process/fuzzers/index>`.
+
+.. _Fuzz testing: https://en.wikipedia.org/wiki/Fuzzing
+
+Important Parts
+---------------
+
+The important parts of the `Project X-Ray` are:
+
+   - *minitests* - designs that can be viewed by a human in Vivado to better
+     understand how to generate more useful designs.
+   - *experiments* - similar to *minitests* except for the fact that they are only
+     useful for a short time.
+   - *tools & libs* - they convert the resulting bitstreams into various formats.
+   - *utils* - tools that are used but still require some testing
+
+.. _Project X-Ray: https://github.com/SymbiFlow/prjxray
+.. _Xilinx: http://www.xilinx.com/
+.. _SymbiFlow: https://symbiflow.readthedocs.io/
+.. _Architecture Definitions: https://github.com/SymbiFlow/symbiflow-arch-defs