Merge pull request #273 from awvwgk/dev-docs

Update developer documentation (manifest + command line)

Author: LKedward

docs.md

@@ -24,9 +24,56 @@ sort: permission-alpha
 favicon: doc/media/favicon.ico
 print_creation_date: true
 extra_mods: iso_fortran_env:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html
+            tomlf:https://toml-f.github.io/toml-f
+            M_CLI2:https://github.com/urbanjost/M_CLI2
 creation_date: %Y-%m-%d %H:%M %z
 md_extensions: markdown.extensions.toc
                markdown.extensions.smarty
 ---
 
 [TOC]
+
+# Fortran package manager developer documentation
+
+This is the main documentation of the Fortran package manager (*fpm*).
+This document serves as developer documentation of *fpm* itself and contains general advice for developing in the *fpm* code base.
+
+
+## The package manifest
+
+The central object describing an *fpm* project is the package manifest ``fpm.toml``.
+The manifest is written in TOML, you can find the TOML specification at the official [TOML homepage](https://toml.io).
+
+The ``fpm.toml`` file targets project developers and maintainers to relieve them from writing build files for their packages.
+With the package manifest a central place to collect information about the project is provided.
+It contains the versioning and licensing meta data, as well as the information on external dependencies and the required build-tools or compiler settings.
+
+The manifest format specific to *fpm* projects is documented in the [manifest reference](page/Manifest.html).
+
+@Note For a more practical but less complete guide on creating *fpm* projects see the [packaging guide](page/Packaging.html).
+
+The details of the TOML parsing are implemented with using the [tomlf](https://toml-f.github.io/toml-f) module.
+Generally, the interface to all TOML related functions for *fpm* is found in the proxy module [[fpm_toml]].
+
+All the manifest types are bundled in [[fpm_manifest]].
+While the specific subtables for the package configuration are found in the ``src/fpm/manifest`` directory, they should be reexported in the [[fpm_manifest]] module if they should be elsewhere in *fpm*.
+
+
+## Command line interface
+
+*fpm* is mainly used as a command line tool.
+To work with an *fpm* project as a user you can completely rely on the command line.
+
+The command line interface is build with the [M_CLI2](https://github.com/urbanjost/M_CLI2) module and can be found in [[fpm_command_line]].
+
+
+## Generating this documentation
+
+This documentation is generated by [FORD](https://github.com/Fortran-FOSS-Programmers/FORD).
+For more details on the [project file](https://github.com/fortran-lang/fpm/docs.md) and the comment markup in the source code visit the [FORD documentation](https://github.com/Fortran-FOSS-Programmers/ford/wiki).
+
+To regenerate this documentation run:
+
+```shell
+ford docs.md
+```

fpm/src/fpm/toml.f90

@@ -1,4 +1,4 @@
-!> Interface to TOML processing library.
+!># Interface to TOML processing library
 !>
 !> This module acts as a proxy to the `toml-f` public Fortran API and allows
 !> to selectively expose components from the library to `fpm`.
@@ -10,7 +10,8 @@
 !> This module allows to implement features necessary for `fpm`, which are
 !> not yet available in upstream `toml-f`.
 !>
-!> For more details on the library used see: https://toml-f.github.io/toml-f
+!> For more details on the library used see the
+!> [TOML-Fortran](https://toml-f.github.io/toml-f) developer pages.
 module fpm_toml
     use fpm_error, only : error_t, fatal_error, file_not_found_error
     use fpm_strings, only : string_t

fpm/src/fpm_command_line.f90

@@ -1,3 +1,27 @@
+!># Definition of the command line interface
+!>
+!> This module uses [M_CLI2](https://github.com/urbanjost/M_CLI2) to define
+!> the command line interface.
+!> To define a command line interface create a new command settings type
+!> from the [[fpm_cmd_settings]] base class or the respective parent command
+!> settings.
+!>
+!> The subcommand is selected by the first non-option argument in the command
+!> line. In the subcase block the actual command line is defined and transferred
+!> to an instance of the [[fpm_cmd_settings]], the actual type is used by the
+!> *fpm* main program to determine which command entry point is chosen.
+!>
+!> To add a new subcommand add a new case to select construct and specify the
+!> wanted command line and the expected default values.
+!> Some of the following points also apply if you add a new option or argument
+!> to an existing *fpm* subcommand.
+!> Add this point you should create a help page for the new command in a simple
+!> catman-like format as well in the ``set_help`` procedure.
+!> Make sure to register new subcommands in the ``fpm-manual`` command by adding
+!> them to the manual character array and in the help/manual case as well.
+!> You should add the new command to the synopsis section of the ``fpm-list``,
+!> ``fpm-help`` and ``fpm --list`` help pages below to make sure the help output
+!> is complete and consistent as well.
 module fpm_command_line
 use fpm_environment,  only : get_os_type, get_env, &
                              OS_UNKNOWN, OS_LINUX, OS_MACOS, OS_WINDOWS, &