mirror of
https://github.com/JHUAPL/kami.git
synced 2026-01-09 14:58:02 -05:00
Documentation moved to Sphinx/RTD
This commit is contained in:
James P. Howard, II
@@ -31,7 +31,7 @@ include(ConfigSafeGuards)
|
||||
include(Colors)
|
||||
include(CTest)
|
||||
include(Doctest)
|
||||
include(Documentation)
|
||||
#include(Documentation)
|
||||
include(LTO)
|
||||
include(Misc)
|
||||
include(Warnings)
|
||||
@@ -87,3 +87,4 @@ set_target_properties(
|
||||
|
||||
# Set up tests (see tests/CMakeLists.txt).
|
||||
add_subdirectory(tests)
|
||||
add_subdirectory(docs)
|
||||
|
||||
114
README.md
114
README.md
@@ -1,110 +1,6 @@
|
||||
[](http://www.repostatus.org/#active)
|
||||
[](https://travis-ci.org/bsamseth/cpp-project)
|
||||
[](https://ci.appveyor.com/project/bsamseth/cpp-project/branch/master)
|
||||
[](https://coveralls.io/github/bsamseth/cpp-project?branch=master)
|
||||
[](https://codecov.io/gh/bsamseth/cpp-project)
|
||||
[](https://www.codacy.com/app/bsamseth/cpp-project?utm_source=github.com&utm_medium=referral&utm_content=bsamseth/cpp-project&utm_campaign=Badge_Grade)
|
||||
[](https://lgtm.com/projects/g/bsamseth/cpp-project/context:cpp)
|
||||
[](https://lgtm.com/projects/g/bsamseth/cpp-project/alerts/)
|
||||
[](https://github.com/bsamseth/cpp-project/blob/master/LICENSE)
|
||||
[](https://github.com/Aaronepower/tokei)
|
||||
[](http://isitmaintained.com/project/bsamseth/cpp-project "Average time to resolve an issue")
|
||||
[](http://isitmaintained.com/project/bsamseth/cpp-project "Percentage of issues still open")
|
||||
|
||||
# Boiler plate for C++ projects
|
||||
|
||||
This is a boiler plate for C++ projects. What you get:
|
||||
|
||||
- Sources, headers and mains separated in distinct folders
|
||||
- Use of modern [CMake](https://cmake.org/) for much easier compiling
|
||||
- Setup for tests using [doctest](https://github.com/onqtam/doctest)
|
||||
- Continuous testing with [Travis-CI](https://travis-ci.org/) and [Appveyor](https://www.appveyor.com), with support for C++17.
|
||||
- Code coverage reports, including automatic upload to [Coveralls.io](https://coveralls.io/) and/or [Codecov.io](https://codecov.io)
|
||||
- Code documentation with [Doxygen](http://www.stack.nl/~dimitri/doxygen/)
|
||||
|
||||
|
||||
|
||||
## Structure
|
||||
``` text
|
||||
.
|
||||
├── CMakeLists.txt
|
||||
├── app
|
||||
│ └── main.cpp
|
||||
├── include
|
||||
│ ├── example.h
|
||||
│ └── exampleConfig.h.in
|
||||
├── src
|
||||
│ └── example.cpp
|
||||
└── tests
|
||||
├── dummy.cpp
|
||||
└── main.cpp
|
||||
```
|
||||
|
||||
Sources go in [src/](src/), header files in [include/](include/), main programs in [app/](app), and
|
||||
tests go in [tests/](tests/) (compiled to `unit_tests` by default).
|
||||
|
||||
If you add a new executable, say `app/hello.cpp`, you only need to add the following two lines to [CMakeLists.txt](CMakeLists.txt):
|
||||
|
||||
``` cmake
|
||||
add_executable(main app/main.cpp) # Name of exec. and location of file.
|
||||
target_link_libraries(main PRIVATE ${LIBRARY_NAME}) # Link the executable to lib built from src/*.cpp (if it uses it).
|
||||
```
|
||||
|
||||
You can find the example source code that builds the `main` executable in [app/main.cpp](app/main.cpp) under the `Build` section in [CMakeLists.txt](CMakeLists.txt).
|
||||
If the executable you made does not use the library in [src/](src), then only the first line is needed.
|
||||
|
||||
|
||||
|
||||
## Building
|
||||
|
||||
Build by making a build directory (i.e. `build/`), run `cmake` in that dir, and then use `make` to build the desired target.
|
||||
|
||||
Example:
|
||||
|
||||
``` bash
|
||||
> mkdir build && cd build
|
||||
> conan install ..
|
||||
> cmake .. -DCMAKE_BUILD_TYPE=[Debug | Coverage | Release]
|
||||
> make
|
||||
> ./main
|
||||
> make test # Makes and runs the tests.
|
||||
> make coverage # Generate a coverage report.
|
||||
> make doc # Generate html documentation.
|
||||
```
|
||||
|
||||
## .gitignore
|
||||
|
||||
The [.gitignore](.gitignore) file is a copy of the [Github C++.gitignore file](https://github.com/github/gitignore/blob/master/C%2B%2B.gitignore),
|
||||
with the addition of ignoring the build directory (`build/`).
|
||||
|
||||
## Services
|
||||
|
||||
If the repository is activated with Travis-CI, then unit tests will be built and executed on each commit.
|
||||
The same is true if the repository is activated with Appveyor.
|
||||
|
||||
If the repository is activated with Coveralls/Codecov, then deployment to Travis will also calculate code coverage and
|
||||
upload this to Coveralls.io and/or Codecov.io
|
||||
|
||||
## Setup
|
||||
|
||||
### Using the GitHub template
|
||||
Click the `Use this template` button to make a new repository from this template.
|
||||
|
||||
**NB**: GitHub templates do not carry over submodules, which means you need to add those back _before_ you can build the project. Run the following after you have generated your new project:
|
||||
``` bash
|
||||
> git clone https://github.com/<your-username>/<your-repo-name>
|
||||
> git submodule add https://github.com/onqtam/doctest.git external/doctest
|
||||
> git commit -a --amend --no-edit
|
||||
> git push --force
|
||||
```
|
||||
|
||||
### From command line
|
||||
When starting a new project, you probably don't want the history of this repository. To start fresh you can use
|
||||
the [setup script](setup.sh) as follows:
|
||||
``` bash
|
||||
> git clone --recurse-submodules https://github.com/bsamseth/cpp-project # Or use ssh-link if you like.
|
||||
> cd cpp-project
|
||||
> bash setup.sh
|
||||
```
|
||||
The result is a fresh Git repository with one commit adding all files from the boiler plate.
|
||||
# Kami Agent-Based Modeling in C++
|
||||
|
||||
This package is largely based on the [Mesa: Agent-based modeling
|
||||
in Python 3+](https://mesa.readthedocs.io/en/master/)
|
||||
package. However, allowances are made for "idiomatic" implementation
|
||||
in C++.
|
||||
|
||||
11
cmake/FindSphinx.cmake
Normal file
11
cmake/FindSphinx.cmake
Normal file
@@ -0,0 +1,11 @@
|
||||
#Look for an executable called sphinx-build
|
||||
find_program(SPHINX_EXECUTABLE
|
||||
NAMES sphinx-build
|
||||
DOC "Path to sphinx-build executable")
|
||||
|
||||
include(FindPackageHandleStandardArgs)
|
||||
|
||||
#Handle standard arguments to find_package like REQUIRED and QUIET
|
||||
find_package_handle_standard_args(Sphinx
|
||||
"Failed to find sphinx-build executable"
|
||||
SPHINX_EXECUTABLE)
|
||||
59
docs/CMakeLists.txt
Normal file
59
docs/CMakeLists.txt
Normal file
@@ -0,0 +1,59 @@
|
||||
find_package(Doxygen REQUIRED)
|
||||
find_package(Sphinx REQUIRED)
|
||||
|
||||
# Find all the public headers
|
||||
get_target_property(KAMI_PUBLIC_HEADER_DIR kami INTERFACE_INCLUDE_DIRECTORIES)
|
||||
file(GLOB_RECURSE KAMI_PUBLIC_HEADERS ${KAMI_PUBLIC_HEADER_DIR}/kami/*.hpp)
|
||||
|
||||
set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/include/kami)
|
||||
set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR})
|
||||
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
|
||||
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
|
||||
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
|
||||
|
||||
# Replace variables inside @@ with the current values
|
||||
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
|
||||
|
||||
# Doxygen won't create this for us
|
||||
file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
|
||||
|
||||
# Only regenerate Doxygen when the Doxyfile or public headers change
|
||||
add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
|
||||
DEPENDS ${KAMI_PUBLIC_HEADERS}
|
||||
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
|
||||
MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
|
||||
COMMENT "Generating docs"
|
||||
VERBATIM)
|
||||
|
||||
# Nice named target so we can run the job easily
|
||||
add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
|
||||
|
||||
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
|
||||
set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
|
||||
set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
|
||||
|
||||
# Only regenerate Sphinx when:
|
||||
# - Doxygen has rerun
|
||||
# - Our doc files have been updated
|
||||
# - The Sphinx config has been updated
|
||||
add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
|
||||
COMMAND
|
||||
${SPHINX_EXECUTABLE} -b html
|
||||
# Tell Breathe where to find the Doxygen output
|
||||
-Dbreathe_projects.kami=${DOXYGEN_OUTPUT_DIR}/xml
|
||||
${SPHINX_SOURCE} ${SPHINX_BUILD}
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
DEPENDS
|
||||
# Other docs files you want to track should go here (or in some variable)
|
||||
${CMAKE_CURRENT_SOURCE_DIR}/index.rst
|
||||
${DOXYGEN_INDEX_FILE}
|
||||
MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
|
||||
COMMENT "Generating documentation with Sphinx")
|
||||
|
||||
# Nice named target so we can run the job easily
|
||||
add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
|
||||
|
||||
# Add an install target to install the docs
|
||||
include(GNUInstallDirs)
|
||||
install(DIRECTORY ${SPHINX_BUILD}
|
||||
DESTINATION ${CMAKE_INSTALL_DOCDIR})
|
||||
@@ -32,19 +32,19 @@ DOXYFILE_ENCODING = UTF-8
|
||||
# title of most generated pages and in a few other places.
|
||||
# The default value is: My Project.
|
||||
|
||||
PROJECT_NAME = "C++ Boiler Plate"
|
||||
PROJECT_NAME = "Kami"
|
||||
|
||||
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
|
||||
# could be handy for archiving the generated documentation or if some version
|
||||
# control system is used.
|
||||
|
||||
PROJECT_NUMBER =
|
||||
PROJECT_NUMBER = 0.1.0
|
||||
|
||||
# Using the PROJECT_BRIEF tag one can provide an optional one line description
|
||||
# for a project that appears at the top of each page and should give viewer a
|
||||
# quick idea about the purpose of the project. Keep the description short.
|
||||
|
||||
PROJECT_BRIEF =
|
||||
PROJECT_BRIEF = "Kami is Agent-Based Modeling in C++
|
||||
|
||||
# With the PROJECT_LOGO tag one can specify a logo or an icon that is included
|
||||
# in the documentation. The maximum height of the logo should not exceed 55
|
||||
@@ -58,7 +58,7 @@ PROJECT_LOGO =
|
||||
# entered, it will be relative to the location where doxygen was started. If
|
||||
# left blank the current directory will be used.
|
||||
|
||||
OUTPUT_DIRECTORY =
|
||||
OUTPUT_DIRECTORY = "@DOXYGEN_OUTPUT_DIR@"
|
||||
|
||||
# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
|
||||
# directories (in 2 levels) under the output directory of each output format and
|
||||
@@ -771,9 +771,10 @@ WARN_LOGFILE =
|
||||
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
|
||||
# Note: If this tag is empty the current directory is searched.
|
||||
|
||||
INPUT = @CMAKE_CURRENT_SOURCE_DIR@/README.md
|
||||
INPUT += @CMAKE_CURRENT_SOURCE_DIR@/include/ @CMAKE_CURRENT_SOURCE_DIR@/src
|
||||
|
||||
INPUT = @PROJECT_SOURCE_DIR@/README.md
|
||||
INPUT+= @PROJECT_SOURCE_DIR@/include/kami
|
||||
INPUT+= @PROJECT_SOURCE_DIR@/src
|
||||
INPUT+= @PROJECT_SOURCE_DIR@/examples
|
||||
|
||||
FILE_PATTERNS += *.md *.markdown
|
||||
|
||||
@@ -1870,7 +1871,7 @@ MAN_LINKS = NO
|
||||
# captures the structure of the code including all documentation.
|
||||
# The default value is: NO.
|
||||
|
||||
GENERATE_XML = NO
|
||||
GENERATE_XML = YES
|
||||
|
||||
# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
|
||||
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
|
||||
66
docs/conf.py
Normal file
66
docs/conf.py
Normal file
@@ -0,0 +1,66 @@
|
||||
import subprocess, os
|
||||
|
||||
def configureDoxyfile(input_dir, output_dir):
|
||||
|
||||
with open('Doxyfile.in', 'r') as file :
|
||||
filedata = file.read()
|
||||
|
||||
filedata = filedata.replace('@DOXYGEN_INPUT_DIR@', input_dir)
|
||||
filedata = filedata.replace('@DOXYGEN_OUTPUT_DIR@', output_dir)
|
||||
|
||||
with open('Doxyfile', 'w') as file:
|
||||
file.write(filedata)
|
||||
|
||||
# Check if we're running on Read the Docs' servers
|
||||
read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
|
||||
|
||||
breathe_projects = {}
|
||||
if read_the_docs_build:
|
||||
input_dir = '../include/kami'
|
||||
output_dir = 'build'
|
||||
configureDoxyfile(input_dir, output_dir)
|
||||
subprocess.call('doxygen', shell=True)
|
||||
breathe_projects['kami'] = output_dir + 'docs/xml'
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'Kami'
|
||||
copyright = '2020'
|
||||
author = 'James P. Howard, II'
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
#...
|
||||
|
||||
extensions = [ "breathe" ]
|
||||
|
||||
#...
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
|
||||
# -- 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 = 'sphinx_rtd_theme'
|
||||
|
||||
# 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']
|
||||
|
||||
# Breathe Configuration
|
||||
breathe_default_project = "kami"
|
||||
7
docs/index.rst
Normal file
7
docs/index.rst
Normal file
@@ -0,0 +1,7 @@
|
||||
…
|
||||
|
||||
Docs
|
||||
====
|
||||
|
||||
.. doxygennamespace:: kami
|
||||
:members:
|
||||
1
docs/requirements.txt
Normal file
1
docs/requirements.txt
Normal file
@@ -0,0 +1 @@
|
||||
breathe
|
||||
@@ -11,12 +11,19 @@
|
||||
|
||||
namespace kami {
|
||||
|
||||
/// A unique identifier for each agent
|
||||
/**
|
||||
* A unique identifier for each agent
|
||||
*/
|
||||
class AgentID {
|
||||
public:
|
||||
/// Create a new unique identifier
|
||||
/**
|
||||
* Create a new unique identifier
|
||||
*/
|
||||
AgentID();
|
||||
|
||||
/**
|
||||
* Convert the identifier to a human readable string
|
||||
*/
|
||||
std::string toString() const;
|
||||
|
||||
friend bool operator==(const AgentID &, const AgentID &);
|
||||
|
||||
@@ -11,7 +11,6 @@
|
||||
#include <kami/kami.hpp>
|
||||
#include <kami/multigrid2d.hpp>
|
||||
#include <map>
|
||||
#include <mutex>
|
||||
#include <vector>
|
||||
|
||||
namespace kami {
|
||||
@@ -19,6 +18,7 @@ namespace kami {
|
||||
typedef enum NeighborhoodType { Moore,
|
||||
VonNeumann } NeighborhoodType;
|
||||
|
||||
/// asdfasdf
|
||||
class MultiGrid2DCoord {
|
||||
public:
|
||||
MultiGrid2DCoord(int, int);
|
||||
|
||||
Reference in New Issue
Block a user