diff --git a/docs/Build.rst b/docs/Build.rst index eb4c7b2..c14a661 100755 --- a/docs/Build.rst +++ b/docs/Build.rst @@ -1,303 +1,339 @@ =========================== Building the RoSA Framework =========================== .. contents:: :local: -General notes -============= - -* The framework is delivered with a CMake project, which can be used to generate - build projects to build the framework. - -* The provided CMake project supports out-of-tree builds only, i.e. one must use - a separate build directory outside of the RoSA source directory. - Build Dependencies ================== In order to build RoSA, the following tools are required: * `CMake `_ (minimum version 3.6.0 if clang-tidy is used, 2.8.8 otherwise); * Build system of your choice that can be targeted by CMake -- including a - compiler supporting C++14. + compiler supporting *C++14*. The following additional tools are required to generate documentation: * `Doxygen `_ -- for generating API documentation; * `Graphviz `_ -- not necessary, but the API documentation has nicer graphics when `dot` is available; * `Sphinx `_ (with *Python 2*) -- for generating documentation. The following additional tools are required to check and possibly enforce coding standard: * `clang-tidy `_ * `clang-format `_ +General notes +============= + +* The framework is delivered with a CMake project, which can be used to generate + build projects to build the framework. + +* The provided CMake project supports out-of-tree builds only, i.e. one must use + a separate build directory outside of the RoSA source directory. + .. _cmake-variables: CMake Variables =============== Beyond the usual CMake variables, the following project-related options are available: `ROSA_INCLUDE_TOOLS` Generate build targets for RoSA tools. The tools are also built when the option is set to `ON`, which is the default setting. `ROSA_INCLUDE_EXAMPLES` Generate build targets for RoSA examples. The examples are also built when the option is set to `ON`, which is the default setting. `ROSA_ENABLE_PEDANTIC` Compile the framework with using `-pedantic`. The option defaults to `ON`. `ROSA_ENABLE_ASSERTIONS` Enable assertions for non-Debug builds, which defaults to `OFF`. Note that assertions are always enabled for Debug builds and this option is ignored for such builds. +.. _CMake_clang_tidy: + `ROSA_ENABLE_CLANG_TIDY` Run *clang-tidy* checks when building RoSA, which defaults to `OFF`. When the variable is enabled, build targets created by *Makefile* and *Ninja* generators include calls for clang-tidy. Other generators ignore this option. Note that CMake variables `CMAKE__CLANG_TIDY` are set when enabled. Settings for clang-tidy are defined by the file `.clang-tidy` in the RoSA source directory. Consider the following options when the option is enabled: `ROSA_CLANG_TIDY_PATH` Custom path for `clang-tidy` executable. In order to use clang-tidy, CMake needs to find the `clang-tidy` executable. If `clang-tidy` is available via `PATH`, just leave the option empty -- which is default. Set the absolute path of the directory containing the `clang-tidy` executable otherwise. `ROSA_CLANG_TIDY_FIX` Apply suggested clang-tidy fixes to the sources, which defaults to `OFF`. Enable the option only if you know what you are doing. +.. _CMake_clang_format: + `ROSA_INCLUDE_CLANG_FORMAT` **[experimental]** Generate build target -- `format-rosa` -- for formatting RoSA sources with *clang-format*, which defatuls to `OFF`. When the variable is enabled and *CMake is not running on a Windows host*, a build target is generated which can be used to have all the RoSA sources formatted with clang-format. Settings for clang-format are defined by the file `.clang-format` in the RoSA source directory. Note that executing build target `format-rosa` will reformat all the source files *inplace*. Consider the following option when a build target for clang-format is to be generated: `ROSA_CLANG_FORMAT_PATH` Custom path for `clang-format` executable. In order to use clang-format, CMake needs to find the `clang-format` executable. If `clang-format` is available via `PATH`, just leave the option empty -- which is default. Set the absolute path of the directory containing the `clang-format` executable otherwise. `ROSA_LOG_LEVEL` Level of logging to be used, use one of the following valid integer values. ======== ========= Variable Log Level ======== ========= `0` `ERROR` `1` `WARNING` `2` `INFO` `3` `DEBUG` `4` `TRACE` `5` *disabled* ======== ========= Level of logging defaults to *disabled*. `ROSA_INCLUDE_DOCS` Generate build targets for RoSA documentation, defaults to `ON`. Note that the automatic execution of the generated build targets is controlled by the option `ROSA_BUILD_DOCS`. The actual documentations to build are controlled by the options `ROSA_ENABLE_DOXYGEN` and `ROSA_ENABLE_SPHINX`. `ROSA_BUILD_DOCS` Build RoSA documentation automatically as part of the build process. The option defaults to `OFF` and takes effect only if the option `ROSA_INCLUDE_DOCS` is enabled. +.. _CMake_doxygen: + `ROSA_ENABLE_DOXYGEN` Use *doxygen* to generate RoSA API documentation. The option defaults to `OFF` and takes effect only if the option `ROSA_INCLUDE_DOCS` is enabled. Doxygen documentation may be generated by executing build target `doxygen-rosa`, which is done as part of the default build process if `ROSA_BUILD_DOCS` is enabled. Doxygen must be available via `PATH` if the option is enabled. The following options are also available to tune doxygen: `ROSA_DOXYGEN_SVG` Use *svg* instead of *png* files for doxygen graphs. The option defaults to `OFF` and takes effect if the tool *dot* is available via `PATH` to be used to generated graph images. `ROSA_DOXYGEN_EXTERNAL_SEARCH` Enable doxygen external search, which defatuls to `OFF`. The following options need to be set if the option is enabled: `ROSA_DOXYGEN_SEARCHENGINE_URL` URL to use for external search. `ROSA_DOXYGEN_SEARCH_MAPPINGS` Doxygen Search Mappings. +.. _CMake_sphinx: + `ROSA_ENABLE_SPHINX` Use *Sphinx* to generate RoSA documentation. The option defaults to `OFF` and takes effect only if the option `ROSA_INCLUDE_DOCS` is enabled. Sphinx must be available via `PATH` if the option is enabled. The following options are also available to tune Sphinx: `SPHINX_OUTPUT_HTML` Output standalone HTML files. The option defaults to `ON`. Documentation may be generated by executing build target `docs-rosa-html`, which is done as part of the default build process if `ROSA_BUILD_DOCS` is enabled. `SPHINX_OUTPUT_MAN` Output man pages for RoSA tools. The option defaults to `ON`. Man pages may be generated by executing build target `docs-rosa-man`, which is done as part of the default build process if `ROSA_BUILD_DOCS` is enabled. `SPHINX_WARNINGS_AS_ERRORS` When building documentation, treat Sphinx warnings as errors. The option defaults to `ON`. Building RoSA Step-by-Step ========================== Building on Linux with Make --------------------------- Configuring and building the framework on Linux using *Make* is a straightforward process which does not require performing any tricks. The framework compiles with *Clang 3.8.0*. Set C and C++ compilers with the variables `CC` and `CXX`, respectively. Use the CMake variable `CMAKE_BUILD_TYPE` to set the type of build: `Debug`, `Release`. Follows an example on building the framework. You need to have RoSA sources on your computer and Clang executables available via `PATH`.:: rosa-src$ cd .. $ mkdir rosa-build $ cd rosa-build rosa-build$ CC=clang CXX=clang++ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DROSA_LOG_LEVEL=4 ../rosa-src/ [CMake configures and generates without errors] $ make [Make builds the project] You just need to re-run Make in order to re-build the project after changing the source code and the CMake project. In case the CMake project is changed, Make automatically calls CMake to update the build project. In order to build documentation and enforce coding standard, refer to corresponding :ref:`cmake-variables`. Building on Windows with Visual Studio -------------------------------------- Unfortunately, the native MSVC compiler cannot compile the framework. One needs to use Clang with Visual Studio in order to build the framework. There are two alternatives to do that: * using the *Clang/C2* module for *Visual Studio 2017*, * using *LLVM for Windows* as an external toolset for Visual Studio (necessary for older versions of Visual Studio). For using Visual Studio 2017 -- which would be the preferred way -- one needs to select *Clang/C2 (experimental)* on the *Individual components* tab in *Visual Studio Installer*. For using *LLVM for Windows*, one downloads the official binary release from http://llvm.org and consults with its documentation. The release provides integration for Visual Studio versions between 2010 and 2014 (as of LLVM 4.0.0). Having your build system prepared and RoSA sources fetched to your computer, configure and build the framework like this: #. Generate Visual Studio solution with CMake: #. Start CMake. #. Define *source directory* and a separate *build directory* in CMake. #. Click *Configure*. #. Select the proper *generator* for your version of Visual Studio. #. Define your optional toolset (argument for `-T`): * Clang/C2 with VS2017: `v141_clang_c2`. * LLVM for Windows with older VS: `LLVM-vs`. #. Click *Finish*. #. Tune CMake variables as you wish. * Note that Visual Studio Generators are multi-configuration generators, hence you cannot set `CMAKE_BUILD_TYPE`. You need to select a configuration to build in Visual Studio. #. Click *Generate*. .. _CMake-VS2017-Clang-fix: #. Fix the generated Visual Studio projects (*applies for Clang/C2*): * The generated projects define `ExceptionHandling` as `Sync`, which is an invalid value for Clang/C2 and needs to be changed to `Enabled` in all Visual Studio project files: * using GNU command line tools:: rosa-build$ find . -name "*.vcxproj" -print|xargs sed -i -e 's/Sync/Enabled/g' * using PowerShell:: rosa-build> ls -path . -include *.vcxproj -recurse | %{ $f=$_; (gc $f.PSPath) | %{ $_ -replace "Sync", "Enabled" } | sc $f.PSPath } * Note that the project files need to be fixed every time CMake regenerates them, which may happen when building the project in Visual Studio in case you have the CMake project changed in the source directory. #. Build the framework with Visual Studio: #. Open the generated `RoSA.sln` from the build directory with Visual Studio. #. Build the project `ALL_BUILD`. You just need to re-build the project in Visual Studio after changing the source code and the CMake project. In case the CMake project is changed, Visual Studio automatically calls CMake the update the build project. Should you use Clang/C2, do not forget to :ref:`fix the generated Visual Studio projects `. +Build Result +============ + +The build process works in the build directory. After a successful build, one +can find the following final outputs there -- besides some intermediate files. + +Software +-------- + +In the build directory, `include` contains header files which are generated by +CMake and provide configuration-specific information. + +The build process generates static libraries in `lib` and executables -- +examples and tools -- in `bin`. Projects generated by a multi-configuration +generator result in the actual libraries and executables being located in +subdirectories corresponding to different build configurations. + +.. _Build Result Documentation: + +Documentation +------------- + +Documentation is generated in `docs`. + +The general documentation can be found in `docs/html`. Man pages for tools can +be found in `docs/man`. + +The API documentation can be found in `docs/doxygen/html`. diff --git a/docs/Changelog.rst b/docs/Changelog.rst new file mode 100755 index 0000000..7468239 --- /dev/null +++ b/docs/Changelog.rst @@ -0,0 +1,14 @@ +=============================== +Changelog of the RoSA Framework +=============================== + +.. contents:: + :local: + +Next Release +------------ + +Initial internal release. + +TODO summarize what's included... + diff --git a/docs/Dev.rst b/docs/Dev.rst index 939dcb3..eec74a4 100755 --- a/docs/Dev.rst +++ b/docs/Dev.rst @@ -1,62 +1,305 @@ ============================= Developing the RoSA Framework ============================= .. contents:: :local: +This document provides information that might be useful for contributing to +RoSA. Please also consult :doc:`Build`. -* Coding Style -* Documentation +The Source Directory +==================== - * General docs +The source directory consists of the following subdirectories: - * Sphinx - * man pages for tools! +`cmake` + Contains files used for configuring the `CMake Project`_. - * API +`docs` + Contains `Documentation`_-related files. - * Doxygen - * doc namespaces +`examples` + Contains `Examples`_ on using the public API. -* When and how to update CMake project +`include/rosa` + Contains the RoSA public API -- that is the interface of RoSA `Libraries`_. + The directory `include` is to be used as include directory and RoSA header + files are to be included in C++ sources as `"rosa/"`. - * header files and source files - * adding libraries, executables +`lib` + Contains the implementation of the RoSA public API -- that is the + implementation of RoSA `Libraries`_. +`tools` + Contains `Tools`_ based on RoSA features. + + +Software Sources +================ + +The section describes the `Logical Structure`_ of the software sources and what +`Coding Standards`_ are supposed to be followed for the implementation. + +Logical Structure +----------------- + +Various features provided by RoSA are sorted into different `Libraries`_. +`Examples`_ and `Tools`_ using those `Libraries`_ are separated from the +implementation of the RoSA features into different directories. + +Libraries +~~~~~~~~~ + +The framework consists of separate libraries providing different features. The +public interfaces for RoSA libraries are defined in `include/rosa`, while +corresponding implementation is in `lib`. Each library has its own subdirectory +in the mentioned directories. + +RoSA provides the following libraries: + +`config` + Provides information on the configuration used to build the framework, e.g., + version number, log level, assertions, and debugging. + +`support` + Provides general features -- template metaprograms dealing with types, for + instance -- for implementing other libraries. + +`core` + Provides the basic RoSA features, like systems managing agents passing + messages. + +`agent` + Provides features to be used for implementing agents. + +Examples +~~~~~~~~ + +Some simple samples are provided in `examples` to demonstrate how to to use +different parts of the RoSA API. + +Tools +~~~~~ + +Tools, programs based on the RoSA libraries, are implemented in `tools`. + +Coding Standards +---------------- + +RoSA is implemented in standard *C++14* code. All the software sources are to +be written in accordance to the `LLVM Coding Standards`_. + +Documentation Comments +~~~~~~~~~~~~~~~~~~~~~~ + +It is important to remember to document source code using `doxygen comments`_ +as `API Documentation`_ is generated directly from sources. + +Note that the syntax of documentation comments is checked during compilation, +at least when using a GCC-compatible compiler. + +If declarations belonging to a namespace spread to more than one source file, +document the namespace in `include/rosa/config/namespaces.h`. Otherwise, +document the namespace in the only file in which entities of the namespace are +declared. + +Header Files +~~~~~~~~~~~~ + +Follow the recommendations on public and private header files and the usage of +`#include` from the `LLVM Coding Standards`_. + +Use `.h` and `.hpp` extensions to indicate the content of the header file: + +* header files containing any *definition* -- template or inline definition -- + or including another header file with `.hpp` extension have `.hpp` extension; +* header files containing only *declarations* and including only header files + with `.h` extension have `.h` extension. + +Checking and Enforcing the Coding Standards +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The tools `clang-tidy `_ and +`clang-format `_ can be used to +check and enforce the coding standards. The two tools are integrated into the +CMake project, refer to CMake variables +:ref:`ROSA_ENABLE_CLANG_TIDY ` and +:ref:`ROSA_INCLUDE_CLANG_FORMAT `. + +Note that there may be situations when `clang-tidy` checks result in false +positives -- for example, for some cases of the order of `#include` directives. +One can order `clang-tidy` to suppress warnings for a line of code by marking +that line with:: + + // NOLINT + +It may be preferred to diverge from the standard formatting -- for example for +the sake of readability of static definition of arrays following some +structure. One can disable `clang-format` for some lines of code by designating +a range with two special comments as:: + + // clang-format off + + ... clang-format is disabled here ... + + // clang-format on + +Documentation +============= + +The RoSA Framework is delivered with two kinds of documentation: `General +Documentation`_ and `API Documentation`_, generation of both of which is +integrated into the CMake project. + +References between the two documentations are relative addresses corresponding +to the directory structure of the +:ref:`generated documentation `. + +General Documentation +--------------------- + +General documentation is written as +`reStructuredText `_ compiled with +`Sphinx `_. For build integration, refer to the +CMake variable :ref:`ROSA_ENABLE_SPHINX `. + +Documentation files are located in `docs` with extension `.rst`. The main +page of the documentation is `docs/index.rst`. Configuration for building the +documentation is `docs/conf.py`. + +The directory `docs/CommandGuide` contains documentation for each separate +tool. Those pages are included in the HTML documentation via +`docs/CommandGuide/index.rst`. Moreover, man pages can be generated from those +tool documentation pages. + +API Documentation +----------------- + +API documentation is directly generated from sources with +`Doxygen `_. For build integration, refer to the CMake +variable :ref:`ROSA_ENABLE_DOXYGEN `. + +The main page used for the API documentation is `docs/doxygen-mainpage.dox`. +Configuration for generating the API documentation is `docs/doxygen.cfg.in`. + +.. _CMake Project: + +Managing the CMake Project +========================== + +This section briefly summarizes when and how to modify CMake files during +the development process. No general discussion on CMake features is provided +here. + +When modifying `Documentation`_, no need to update the CMake files. + +Software +-------- + +One needs to modify the CMake files only if source files are to be added or +removed from the project. Here follows some typical scenarios. + +Source Files +~~~~~~~~~~~~ + +Each library and executable target has its own directory and its own definition +as a file called `CMakeLists.txt` in that directory. + +When adding or removing a source file -- both headers and `.cpp` files -- to a +library or executable, locate the corresponding `CMakeLists.txt` file. The file +is typically in the same directory where the file to be added or removed is +located. Except for header files of the public API, for which the corresponding +CMake target is defined in a `lib` subdirectory corresponding to the library the +header files belongs to. + +Update the source list in the argument of the `add_library` or `add_executable` +command in the `CMakeLists.txt`, for libraries and executables, respectively. + +A library and executable may use features provided by another library. Such a +dependency is to be defined in the `CMakeLists.txt` file of the dependent +target by using the `ROSA_add_library_dependencies` command. + +CMake Libraries +~~~~~~~~~~~~~~~ + +When adding or removing a library, add or remove the corresponding directories +from `include` and `lib`, and also update `lib/CMakeLists.txt` by adding or +removing a `add_subdirectory` command for the library. + +When defining a new library, the new subdirectory under `lib` needs to contain a +`CMakeLists.txt`, which needs to contain at least an `add_library` command +defining the name of the library and the source files belonging to it. + +CMake Executables +~~~~~~~~~~~~~~~~~ + +When adding or removing an executable, add or remove the corresponding +directory from `examples` or `tools`, and also update `CMakeLists.txt` in the +containing directory as for libraries. + +When defining a new executable, the new subdirectory needs to contain a +`CMakeLists.txt`, which needs to contain at least an `add_executable` command +defining the name of the executable and the source files belonging to it. + +.. _Dev Managing Sources: + +Managing Sources +================ + +Consider the followings before committing changes to the repository: + +* your code complies with the `Coding Standards`_ as much as possible; +* your code is well documented; +* your code is not bloated with unusued code and/or comments; +* your changes do not break building and executing the framework: + + * test all of the supported platforms if possible, + * look into the generated documentation if you have edited + `General Documentation`_; + +* you do not pollute the repository with unused and generated files. + +When committing changes to the repository, provide a concise log message with +your commit. + +Miscellaneous Concerns +====================== Using YCM -========= +--------- If you happen to use `YCM `_, just make a copy of the provided `ycm_extra_conf.py.template` file as `.ycm_extra_conf.py` in the RoSA source directory, and set the following two variables in it: `compilation_database_folder` the absolute path of your build directory `extra_system_include_dirs` any system include directory which might not be searched by `libclang` [1]_. You probably want compile with Clang if you use YCM, so run CMake with environment variables `CC=clang` and `CXX=clang++` set. Also note that header files in the `include` directory are compiled for YCM with the compiler flags of a corresponding source file in the `lib` directory, if any. Header files in other locations are supposed to have a corresponding source file in the same directory. Notes ------ +~~~~~ * If the project's include directory (`include/rosa`) would ever be changed, then the YCM configuration file needs to be adjusted accordingly. ---- .. [1] See: https://github.com/Valloric/YouCompleteMe/issues/303; use the following command to figure out the used system directories: echo | clang -std=c++11 -v -E -x c++ - +.. _`LLVM Coding Standards`: http://llvm.org/docs/CodingStandards.html +.. _`doxygen comments`: http://llvm.org/docs/CodingStandards.html#doxygen-use-in-documentation-comments diff --git a/docs/Issues.rst b/docs/Issues.rst new file mode 100755 index 0000000..f29d84d --- /dev/null +++ b/docs/Issues.rst @@ -0,0 +1,32 @@ +================================================================== +Known Issues with the Current Implementation of the RoSA Framework +================================================================== + +.. contents:: + :local: + +TODO +==== + +* Project logo - `docs/_themes/rosa-theme/static/logo.png` +* CAF license? +* Packaging with + `CPack `_. +* What about a projects directory in parallel to tools? +* What about testing the framework? + +Known Issues +============ + +* CMake + + * VS2017 generates intermediate files for the `ZERO_CHECK` project out of the + build directory, see `CMake issue #16458`_. + * VS2017 with `v141_clang_c2` toolset requires + :ref:`fix of the generated Visual Studio projects `. + +* clang-format + + * `include/rosa/core/Message.hpp` breaks clang-format as of version 3.8.0. + +.. _CMake issue #16458: https://gitlab.kitware.com/cmake/cmake/issues/16458 diff --git a/docs/Plan.rst b/docs/Plan.rst index c3e6311..ad2ab11 100755 --- a/docs/Plan.rst +++ b/docs/Plan.rst @@ -1,28 +1,8 @@ ================================= Future Work on the RoSA Framework ================================= .. contents:: :local: -TODO -==== - -* Project logo - `docs/_themes/rosa-theme/static/logo.png` -* API documentation welcome - `docs/doxygen-mainpage.dox` -* Documentation index - `docs/index.rst` -* Complete initial docs... -* Fix rules in `.clang-format` -* What about testing? - -Known Issues -============ - -* CMake - - * VS2017 generates intermediate files for the `ZERO_CHECK` project out of the - build directory, see `CMake issue #16458`_. - * VS2017 with `v141_clang_c2` toolset requires - :ref:`fix of the generated Visual Studio projects `. - -.. _CMake issue #16458: https://gitlab.kitware.com/cmake/cmake/issues/16458 +Need to define some big plans for RoSA... diff --git a/docs/Release.rst b/docs/Release.rst index cd300e6..11ade0b 100755 --- a/docs/Release.rst +++ b/docs/Release.rst @@ -1,21 +1,55 @@ ============================================= Releasing a new version of the RoSA Framework ============================================= .. contents:: :local: -* what to check +Before Releasing +================ - * coding standard - * build and execute on supported platforms with supported toolsets +:ref:`General recommendations ` should be applied +continually for each separate commit. Nevertheless, check the current state of +sources against those recommendations before creating a release. -* generate the release +Make sure that the changelog is reasonably updated. - * step version number -- CMake, Sphinx conf - * tag - * generate docs - * generate source package - * generate binary packages for supported platforms - * publish on website... +Validate that the project builds and the framework can be executed without +errors on all supported platforms. +Generating a Release +==================== + +Once it is decided to generate a release, follow the steps below. + +#. Set version number of the new release: + + * CMake variables in the main `CMakeLists.txt`: + `ROSA_VERSION_MAJOR`, `ROSA_VERSION_MINOR`, `ROSA_VERSION_PATCH`; + * Sphinx configuration in `docs/conf.py`: + + * `version` as "`ROSA_VERSION_MAJOR.ROSA_VERSION_MINOR`", + * `release` as + "`ROSA_VERSION_MAJOR.ROSA_VERSION_MINOR.ROSA_VERSION_PATH`"; + + * Changelog in `docs/Changelog.rst`. + +#. Commit the version number update and tag the release. +#. Create packages: + + * source package -- just the source directory; + * binary packages for supported platform: + + * create `RELEASE` build without assertions and without logging, + * the package contains: + + * all generated documentation in `docs`, + * public headers -- `include` from source and build directories -- in + `include`, + * libraries in `lib`, + * tool executables in `tools`. + +#. Publish on website: + + * HTML documentation as is; + * packages for download. diff --git a/docs/conf.py b/docs/conf.py index 026865a..cc3cf2d 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,253 +1,253 @@ # -*- coding: utf-8 -*- # # RoSA documentation build configuration file. # # This file is execfile()d with the current directory set to its containing dir. # # Note that not all possible configuration values are present in this # autogenerated file. # # All configuration values have a default; values that are commented out # serve to show the default. import sys, os from datetime import date # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. #sys.path.insert(0, os.path.abspath('.')) # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. #needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' # The encoding of source files. #source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # General information about the project. project = u'RoSA' copyright = u'2016-%d, RoSA' % date.today().year # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0' +version = '0.1' # The full version, including alpha/beta/rc tags. -release = '0' +release = '0.1.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = '' # Else, today_fmt is used as the format for a strftime call. today_fmt = '%Y-%m-%d' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. #add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). #add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. show_authors = True # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'friendly' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] # -- Options for HTML output --------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme = 'rosa-theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. html_theme_options = { "nosidebar": True } # Add any paths that contain custom themes here, relative to this directory. html_theme_path = ["_themes"] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". #html_title = None # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. #html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. #html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. html_last_updated_fmt = '%Y-%m-%d' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. html_sidebars = {'index': 'indexsidebar.html'} # Additional templates that should be rendered to pages, maps page names to # template names. #html_additional_pages = {} # If false, no module index is generated. #html_domain_indices = True # If false, no index is generated. #html_use_index = True # If true, the index is split into individual pages for each letter. #html_split_index = False # If true, links to the reST sources are added to the pages. html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. #html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. #html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. #html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = None # Output file base name for HTML help builder. htmlhelp_basename = 'RoSAdoc' # -- Options for LaTeX output -------------------------------------------------- latex_elements = { # The paper size ('letterpaper' or 'a4paper'). #'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). #'pointsize': '10pt', # Additional stuff for the LaTeX preamble. #'preamble': '', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'RoSA.tex', u'RoSA Documentation', u'RoSA', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. #latex_use_parts = False # If true, show page references after internal links. #latex_show_pagerefs = False # If true, show URL addresses after external links. #latex_show_urls = False # Documents to append as an appendix to all manuals. #latex_appendices = [] # If false, no module index is generated. #latex_domain_indices = True # -- Options for manual page output -------------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [] # Automatically derive the list of man pages from the contents of the command # guide subdirectory. basedir = os.path.dirname(__file__) man_page_authors = "" command_guide_subpath = 'CommandGuide' command_guide_path = os.path.join(basedir, command_guide_subpath) for name in os.listdir(command_guide_path): # Ignore non-ReST files and the index page. if not name.endswith('.rst') or name in ('index.rst',): continue # Otherwise, automatically extract the description. file_subpath = os.path.join(command_guide_subpath, name) with open(os.path.join(command_guide_path, name)) as f: title = f.readline().rstrip('\n') header = f.readline().rstrip('\n') if len(header) != len(title): print >>sys.stderr, ( "error: invalid header in %r (does not match title)" % ( file_subpath,)) if ' - ' not in title: print >>sys.stderr, ( ("error: invalid title in %r " "(expected ' - ')") % ( file_subpath,)) # Split the name out of the title. name,description = title.split(' - ', 1) man_pages.append((file_subpath.replace('.rst',''), name, description, man_page_authors, 1)) # If true, show URL addresses after external links. #man_show_urls = False # FIXME: Define intersphinx configuration. intersphinx_mapping = {} diff --git a/docs/doxygen-mainpage.dox b/docs/doxygen-mainpage.dox index f7025e3..1727b97 100755 --- a/docs/doxygen-mainpage.dox +++ b/docs/doxygen-mainpage.dox @@ -1,15 +1,17 @@ /// \mainpage RoSA /// /// \section main_intro Introduction /// Welcome to RoSA. /// -/// TODO What this documentation is about? +/// These pages provide API documentation generated from the source code with +/// doxygen. For general documentation on RoSA, please proceed +/// this way. /// /// \section main_caveat Caveat /// This documentation is generated directly from the source code with doxygen. /// Since RoSA is constantly under active development, what you're about to /// read is out of date! However, it may still be useful since certain portions /// of RoSA are stable. /// -/// \section main_changelog Change Log -/// - Original content written +/// \section main_changelog Changelog +/// Refer to the RoSA Changelog. diff --git a/docs/index.rst b/docs/index.rst index eee93a0..1b33d97 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,48 +1,68 @@ +================== +The RoSA Framework +================== + +.. contents:: + :local: + Overview ======== -TODO Overview of RoSA... +The RoSA (Research on Self-Awareness) Framework is intended to be used as a tool +for experimenting and evaluating new ways of implementing self-aware +applications. Documentation ============= .. toctree:: :hidden: + Changelog Use Build Dev + Issues Release Plan CommandGuide/index :doc:`Use` Describes how to create your own software based on RoSA. :doc:`Build` Describes how to build RoSA. :doc:`Dev` Provides basic information for developers on how to contribute to RoSA. +:doc:`Issues` + Known issues and things to do with the current implementation of RoSA. + :doc:`Release` Describes for maintainers how to make a new release of RoSA. :doc:`Plan` Discusses future work and possible ways to develop RoSA. +.. + :doc:`CommandGuide/index` + Documentation for RoSA tools. + +Changes +======= + +Refer to :doc:`Changelog`. + API Documentation ================= -For details of the provided interface, refer to our `Doxygen documentation`_. +For details of the provided interface, refer to our `API documentation`_. -.. - Relative address to doxygen docs in the build directory, - TODO: adjust it for the website once having one. -.. _Doxygen documentation: ../doxygen/html/index.html +.. _API documentation: ../doxygen/html/index.html -Indices and tables +Indices and Tables ================== * :ref:`genindex` * :ref:`search`