Skip to content

Commit

Permalink
Add documentation and bump version number.
Browse files Browse the repository at this point in the history
  • Loading branch information
@beroset
beroset committed Nov 8, 2020
1 parent a96d8df commit 64816a0
Show file tree
Hide file tree
Showing 8 changed files with 3,004 additions and 9 deletions.
14 changes: 9 additions & 5 deletions CMakeLists.txt
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
cmake_minimum_required(VERSION 3.1)
project(autoproject)
if (POLICY CMP0048)
cmake_policy(SET CMP0048 NEW)
endif (POLICY CMP0048)

project(autoproject VERSION 2.1.0)
set(CMAKE_CXX_STANDARD 17)
set(CPACK_PACKAGE_VERSION_MAJOR "2")
set(CPACK_PACKAGE_VERSION_MINOR "0")
set(CPACK_PACKAGE_VERSION_PATCH "0")
set (CPACK_RESOURCE_FILE_LICENSE
"${CMAKE_CURRENT_SOURCE_DIR}/LICENSE")
set(CPACK_PACKAGE_VENDOR "beroset")
SET(CPACK_SOURCE_IGNORE_FILES "/build/;/*.swp;.git*")
set(CPACK_SOURCE_IGNORE_FILES "/build/;/*.swp;.git*")
set(CPACK_PACKAGE_NAME autoproject)

# defines CMAKE_INSTALL_DATADIR and friends
Expand All @@ -27,6 +28,9 @@ configure_file (
# so that we will find config.h
include_directories("${PROJECT_BINARY_DIR}")

# Create the documentation
add_subdirectory(doc)

add_subdirectory(src)
add_subdirectory(bin)
add_subdirectory(config)
Expand Down
61 changes: 61 additions & 0 deletions doc/01_intro.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Introduction {#mainpage} #
Reviewing code on [CodeReview](http://codereview.stackexchange.com) doesn't necessarily require actually *building* it, but it's often helpful to do so in order to evaluate fully. I usually create a `CMake` project and build from there and this project was how I automated part of the process.

## How to use it
Here's how to use this code. First fetch or create a markdown file (`.md` file) that contains the full source code for a C++ project. To fetch one from [CodeReview](http://codereview.stackexchange.com), you may use `bin/fetchQ` which is a Python program designed for this purpose. As an example, let's use http://codereview.stackexchange.com/questions/93775/compile-time-sieve-of-eratosthenes

To fetch the `.md` file for that question, we need to note the number (93775 in this case) and choose a name (let's say `sieve.md`). Then use the command `fetchQ 93775 sieve.md`. This fetches the `.md` file from the CodeReview site and puts it in the current directory.

Now that we have an `.md` file, (named `sieve.md` for this example), we can simply run this code using the command line: `autoproject sieve.md`

This will automatically parse the `sieve.md` file and extract the files it finds to a directory tree like this.

<!-- language: lang-none -->

sieve
├── build (empty subdirectory)
├── CMakeLists.txt (generated)
└── src
├── CMakeLists.txt (generated)
├── primeconst.cpp (extracted)
├── primeconst.h (extracted)
└── primeconsttest.cpp (extracted)

For much code in many questions, all that is then required is to navigate to the `build` directory and then type:

cmake ..
make

The executable (if successfully created) will be created in `build/src` and will be named `sieve` (or whatever more meaningful name you have given the original `.md` file). Examples of questions for which this works are http://codereview.stackexchange.com/questions/123489/recursive-breadth-first-search-for-knights-tour and http://codereview.stackexchange.com/questions/78362/hangman-on-the-command-line.

Note that this may not work if there are special things needed by the code in question that are unknown to the software. For instance, this code itself will build because there is a built-in rules that looks for the `#include <experimental/filesystem>` and, if found, adds the following line to the resulting CMake file:

target_link_libraries(${EXECUTABLE_NAME} stdc++fs)

Other software packages (e.g. some parts of Boost) do not currently have built-in rules.

Note also, that `CMake` will automatically use the environment variables `CFLAGS` and `CXXFLAGS`. My setup, which works well for many programs including this one includes `CXXFLAGS="-Wall -Wextra -pedantic"`. By default, this program generates CMake files that specify C++14 for platforms that recognize the standard compliance level (e.g. `gcc` and `clang` but not `MSVC`).

So far, this program has been tested and run successfully on Linux and Windows.

## How to build
### Linux
On most Linux machines with CMake installed, building will look something like this:

mkdir build
cd build
cmake ..
make

The executable will then be in the `build/src/` directory and is named `autoproject`.

### Windows
Under Windows with MSVC++17 or better with CMake installed:

mkdir winbuild
cd winbuild
cmake ..
msbuild autoproject.sln

The executable will then be in the `winbuild\src\Debug` directory and is named `autoproject`.

42 changes: 42 additions & 0 deletions doc/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
find_package(Doxygen 1.8.16)
set(MD_SOURCES 01_intro.md )
set(IMAGE_PATH "images")
set(DEST_IMAGE_PATH "${CMAKE_BINARY_DIR}/${IMAGE_PATH}")
if(DOXYGEN_FOUND)
configure_file(
"${autoproject_SOURCE_DIR}/doc/doxygen.conf.in"
"${CMAKE_BINARY_DIR}/doxygen.conf"
@ONLY
)
configure_file(
"${autoproject_SOURCE_DIR}/doc/header.tex"
"${CMAKE_BINARY_DIR}/doc/header.tex"
COPYONLY
)
add_custom_target(
doc
"${DOXYGEN_EXECUTABLE}"
"${CMAKE_BINARY_DIR}/doxygen.conf"
WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
DEPENDS "${MD_SOURCES}"
DEPENDS "${DEST_IMAGE_PATH}/npn.png"
COMMENT "Generating API Reference documentation..." VERBATIM
)
add_custom_target(
pdf
DEPENDS "${CMAKE_BINARY_DIR}/doc/latex/refman.pdf"
)
add_custom_command(
OUTPUT "${CMAKE_BINARY_DIR}/doc/latex/refman.pdf"
COMMAND "make"
DEPENDS "doc"
WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/doc/latex"
COMMENT "Generating PDF format Reference documentation..." VERBATIM
)
add_custom_command(
OUTPUT "${DEST_IMAGE_PATH}/npn.png"
COMMAND "${CMAKE_COMMAND}" -E copy_directory "${CMAKE_CURRENT_LIST_DIR}/${IMAGE_PATH}" "${DEST_IMAGE_PATH}"
COMMENT "Copying image files..." VERBATIM
)

endif(DOXYGEN_FOUND)
194 changes: 194 additions & 0 deletions doc/DoxygenLayout.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
<doxygenlayout version="1.0">
<!-- Generated by doxygen 1.8.11 -->
<!-- Navigation index tabs for HTML output -->
<navindex>
<tab type="mainpage" visible="yes" title=""/>
<tab type="pages" visible="yes" title="" intro=""/>
<tab type="modules" visible="yes" title="" intro=""/>
<tab type="namespaces" visible="yes" title="">
<tab type="namespacelist" visible="yes" title="" intro=""/>
<tab type="namespacemembers" visible="yes" title="" intro=""/>
</tab>
<tab type="classes" visible="yes" title="">
<tab type="classlist" visible="yes" title="" intro=""/>
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
<tab type="hierarchy" visible="yes" title="" intro=""/>
<tab type="classmembers" visible="yes" title="" intro=""/>
</tab>
<tab type="files" visible="yes" title="">
<tab type="filelist" visible="yes" title="" intro=""/>
<tab type="globals" visible="yes" title="" intro=""/>
</tab>
<tab type="examples" visible="yes" title="" intro=""/>
</navindex>

<!-- Layout definition for a class page -->
<class>
<briefdescription visible="yes"/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<inheritancegraph visible="$CLASS_GRAPH"/>
<collaborationgraph visible="$COLLABORATION_GRAPH"/>
<memberdecl>
<nestedclasses visible="yes" title=""/>
<publictypes title=""/>
<services title=""/>
<interfaces title=""/>
<publicslots title=""/>
<signals title=""/>
<publicmethods title=""/>
<publicstaticmethods title=""/>
<publicattributes title=""/>
<publicstaticattributes title=""/>
<protectedtypes title=""/>
<protectedslots title=""/>
<protectedmethods title=""/>
<protectedstaticmethods title=""/>
<protectedattributes title=""/>
<protectedstaticattributes title=""/>
<packagetypes title=""/>
<packagemethods title=""/>
<packagestaticmethods title=""/>
<packageattributes title=""/>
<packagestaticattributes title=""/>
<properties title=""/>
<events title=""/>
<privatetypes title=""/>
<privateslots title=""/>
<privatemethods title=""/>
<privatestaticmethods title=""/>
<privateattributes title=""/>
<privatestaticattributes title=""/>
<friends title=""/>
<related title="" subtitle=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<enums title=""/>
<services title=""/>
<interfaces title=""/>
<constructors title=""/>
<functions title=""/>
<related title=""/>
<variables title=""/>
<properties title=""/>
<events title=""/>
</memberdef>
<allmemberslink visible="yes"/>
<usedfiles visible="$SHOW_USED_FILES"/>
<authorsection visible="yes"/>
</class>

<!-- Layout definition for a namespace page -->
<namespace>
<briefdescription visible="yes"/>
<memberdecl>
<nestednamespaces visible="yes" title=""/>
<constantgroups visible="yes" title=""/>
<classes visible="yes" title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
</memberdef>
<authorsection visible="yes"/>
</namespace>

<!-- Layout definition for a file page -->
<file>
<briefdescription visible="yes"/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<includegraph visible="$INCLUDE_GRAPH"/>
<includedbygraph visible="$INCLUDED_BY_GRAPH"/>
<sourcelink visible="yes"/>
<memberdecl>
<classes visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<constantgroups visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
</memberdef>
<authorsection/>
</file>

<!-- Layout definition for a group page -->
<group>
<briefdescription visible="yes"/>
<groupgraph visible="$GROUP_GRAPHS"/>
<memberdecl>
<nestedgroups visible="yes" title=""/>
<dirs visible="yes" title=""/>
<files visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<classes visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<pagedocs/>
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
</memberdef>
<authorsection visible="yes"/>
</group>

<!-- Layout definition for a directory page -->
<directory>
<briefdescription visible="yes"/>
<directorygraph visible="yes"/>
<memberdecl>
<dirs visible="yes"/>
<files visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
</directory>
</doxygenlayout>
Loading

0 comments on commit 64816a0

Please sign in to comment.