From b400895f1d49f65e18f8e8987dbf421e94888e35 Mon Sep 17 00:00:00 2001 From: Marco Randazzo Date: Wed, 22 Nov 2023 23:57:37 +0100 Subject: [PATCH] doxygen documentation fixed --- .github/CONTRIBUTING.md | 45 +++++------------------ .github/workflows/tag.yml | 4 +- doc/001_installation/1_download.dox | 34 +---------------- doc/100_other/3_writing_documentation.dox | 14 +++---- doc/Doxyfile.in | 19 +++++----- doc/releases.md | 9 ++++- doc/yarp-doxygen-layout.xml | 2 +- 7 files changed, 37 insertions(+), 90 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index dc00264ecb1..587fbbc67d1 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,31 +1,6 @@ Contributing to YARP {#contributing} ==================== - - - -**Table of Contents** - -- [Code Style](#code-style) - - [C++](#c) - - [Header guards](#header-guards) - - [CMake](#cmake) - - [Git](#git) -- [Workflow](#workflow) - - [Stable branches: `yarp-3.x`](#stable-branches-yarp-3x) - - [Work in progress PR](#work-in-progress-pr) - - [Development branch: `master`](#development-branch-master) - - [Example](#example) - - [Terminology](#terminology) -- [Policies](#policies) - - [Deprecated Features](#deprecated-features) - - [`impl` Classes](#impl-classes) - - [Supported Systems](#supported-systems) - - - - - Code Style ---------- @@ -98,7 +73,7 @@ Example: Workflow -------- -### Stable branches: `yarp-3.x` +### Stable branches: yarp-3.x The `yarp-3.x` branch is stable and **should not receive new features**. Only **bug fixes** are accepted. @@ -146,7 +121,7 @@ Once you're happy about your work, just remove the `[WIP]` tag as well as the la and drop a message within the PR to notify the community that reviews are welcome and merging is now possible. -### Development branch: `master` +### Development branch: master We use the branch `master` to collect the ongoing work, which is given in terms @@ -218,19 +193,19 @@ major release, in order to simplify as much as possible the migration. During this period, it is also allowed to do breaking changes that cannot be deprecated using the `YARP_DEPRECATED` methods. -### `impl` Classes +### Impl Classes Classes in the "impl" namespace are not considered public. Their API is subject to changes, without deprecation, even in a minor release. - ### Supported Systems -* **Linux**: See [YARP Supported Distributions](http://wiki.icub.org/wiki/YARP_Supported_Distributions) +* **Linux**: + * Ubuntu 22.04 - clang 17 + * Ubuntu 22.04 - gcc 11.4.0 * **Windows**: - * Visual Studio 15 2017 32/64 bit - * Visual Studio 16 2019 32/64 bit + * Windows 10.0.17763 - VS 16.11.2.50704 + * Windows 10.0.20348 - VS 17.8.34309.116 * **macOS**: - * 10.13 High Sierra - * 10.14 Mojave - * 10.15 Catalina + * macOS 12.6.9 - clang 14.0.3 + * macOS 13.6 - clang 14.0.3 diff --git a/.github/workflows/tag.yml b/.github/workflows/tag.yml index 11843c1f5d2..b0f29c7cb63 100644 --- a/.github/workflows/tag.yml +++ b/.github/workflows/tag.yml @@ -236,8 +236,8 @@ jobs: echo "Update the file 'doc/001_installation/1_download.dox'" # WARNING This is based on the line in the file, it could stop working # if the content of the file changes. - # Move line 8 to line 57 - sed -i -e '8{h;d};57{p;g}' doc/001_installation/1_download.dox + # Move line 8 to line 25 + sed -i -e '8{h;d};25{p;g}' doc/001_installation/1_download.dox # Add the new release at line 8 sed -i "8i\\ + \\\\ref v${YARP_VERSION_C}" doc/001_installation/1_download.dox diff --git a/doc/001_installation/1_download.dox b/doc/001_installation/1_download.dox index 220628279a4..2d430221ffd 100644 --- a/doc/001_installation/1_download.dox +++ b/doc/001_installation/1_download.dox @@ -15,39 +15,7 @@ Latest release can be downloaded from here: \section download_binary Binary releases -\subsection download_windows Windows - -\remark Important: to develop code using precompiled binaries packages have to - match the compiler you use, make sure you download and install the - correct version (i.e. MSVC 12 for Visual Studio 2013, etc..). - If in doubt about the version number of your copy of Visual Studio, find - the internal version number shown for it in this - [version history table](http://en.wikipedia.org/wiki/Microsoft_Visual_Studio#History). - -__Installers__: - -| | MSVC 2015/2017 | -|-------|:---------------------------------:| -| Win32 | [yarp_3.1.0_v14_x86_1.exe] | -| x64 | [yarp_3.1.0_v14_x86_amd64_1.exe] | - -[yarp_3.1.0_v14_x86_1.exe]: https://github.com/robotology/yarp/releases/download/v3.1.0/yarp_3.1.0_v14_x86_1.exe -[yarp_3.1.0_v14_x86_amd64_1.exe]: https://github.com/robotology/yarp/releases/download/v3.1.0/yarp_3.1.0_v14_x86_amd64_1.exe - - -\subsection download_linux Linux (Debian/Ubuntu) - -The easiest way to install YARP from binaries is through aptitude as explained in \ref install_on_linux. - -Individual .deb packages can also be downloaded from [GitHub](https://github.com/robotology/yarp/releases) - - -\subsection download_macOS macOS - -The easiest way to install YARP from binaries is through brew as explained in \ref install_yarp_mac. - -Brew bottles can also be downloaded from [GitHub](https://github.com/robotology/yarp/releases) - +Currently not available. \section download_previous_releases Previous releases diff --git a/doc/100_other/3_writing_documentation.dox b/doc/100_other/3_writing_documentation.dox index b4335ade481..e0730b3f647 100644 --- a/doc/100_other/3_writing_documentation.dox +++ b/doc/100_other/3_writing_documentation.dox @@ -1,27 +1,27 @@ /** \page writing_documentation Yarp Doxygen Documentation -Yarp documentation is writteng using Doxygen. +Yarp documentation is written using Doxygen. This files explains how the Yarp documentation is generated, and how to contribute to it if you are not familiar with Doxygen. -\section code documentation +\section code_doc code documentation - Software components should be documented using the `\ingroup` directive, so that they will be ordered under a specific yarp module. -\section non-code docuemtnation +\section non-code_doc non-code documentation -- documentation is consituted by a set of .dox and .md files (.md files are parsed by Doxygen too) +- documentation is constituted by a set of .dox and .md files (.md files are parsed by Doxygen too) - Doxygen shows the pages in the index in alphabetical order using the .dox filename, not the page name. This is the reason why files are ordered using 000_xxx, 001_yyy folders. - Pages are defined through a `\page` directive and automatically put by doxygen in the `Other pages` section. - If another page references a page using the `\subpage` directive, then the page is removed from the main level of index tree (i.e. `Other pages` ) and put as child of the parent page. -- If you want to avoid this, use the `\ref` directive. This directive will not generate a parent-child relationship (and thus it will be not dislayed in the index tree). +- If you want to avoid this, use the `\ref` directive. This directive will not generate a parent-child relationship (and thus it will be not displayed in the index tree). -- modules are defined using the `\defgroup` directive and are tipically used to define stand-alone components such as libraries. +- modules are defined using the `\defgroup` directive and are typically used to define stand-alone components such as libraries. - a component can be associated to a module using the `\ingroup` directive. - pages and modules should not be mixed! - a module can refer to other pages using the `\ref` directive. (e.g. to provide a link to a tutorial). -- The entrypoint of the documentation is the file main.dox. This only uses `/ref` directives and not `subpage` directives in order not to have child pages. All pages should be independent. +- The entry point of the documentation is the file main.dox. This only uses `/ref` directives and not `subpage` directives in order not to have child pages. All pages should be independent. - The `\section` directive is always allowed, both in main.dox and in all other pages. */ diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 856c94f559c..342573d7a5f 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -956,15 +956,8 @@ RECURSIVE = YES EXCLUDE = @CMAKE_SOURCE_DIR@/.github/git-workflow \ @CMAKE_SOURCE_DIR@/src/devices/README.md \ - @CMAKE_SOURCE_DIR@/src/portmonitors/depthimage_compression_zlib/README.md \ - @CMAKE_SOURCE_DIR@/src/portmonitors/image_compression_ffmpeg/README.md \ - @CMAKE_SOURCE_DIR@/src/portmonitors/depthimage_compression_zfp/README.md \ - @CMAKE_SOURCE_DIR@/src/portmonitors/bottle_compression_zlib/README.md \ - @CMAKE_SOURCE_DIR@/src/portmonitors/depthimage_to_vector/README.md \ - @CMAKE_SOURCE_DIR@/src/portmonitors/sensorMeasurements_to_vector/README.md \ - @CMAKE_SOURCE_DIR@/src/portmonitors/sound_marker/README.md \ - @CMAKE_SOURCE_DIR@/src/portmonitors/soundfilter_resample/README.md - @CMAKE_SOURCE_DIR@/doc/release/yarp_* + @CMAKE_SOURCE_DIR@/src/portmonitors/README.md \ + @CMAKE_SOURCE_DIR@/src/carriers/README.md # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -980,7 +973,13 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = */doc/release/yarp_* \ + */opt-modules/*/README.md \ + */opt-modules/*/CHANGELOG.md \ + */opt-modules/*/*.md \ + */src/devices/*/README.md \ + */src/portmonitors/*/README.md \ + */src/carriers/*/README.md # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the diff --git a/doc/releases.md b/doc/releases.md index e5d66a4462b..b3d21c0222c 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -3,14 +3,19 @@ YARP ChangeLog {#changelog} This page lists the main changes introduced in YARP at each release. +## YARP 3.9 Series {#yarp_3_9_series} +* \subpage v3_9_0 + +## YARP 3.8 Series {#yarp_3_8_series} +* \subpage v3_8_1 +* \subpage v3_8_0 ## YARP 3.7 Series {#yarp_3_7_series} -* \subpage yarp_3_7 * \subpage v3_7_2 * \subpage v3_7_1 * \subpage v3_7_0 + ## YARP 3.6 Series {#yarp_3_6_series} -* \subpage yarp_3_6 * \subpage v3_6_0 ## YARP 3.5 Series {#yarp_3_5_series} diff --git a/doc/yarp-doxygen-layout.xml b/doc/yarp-doxygen-layout.xml index 36c589ddd25..70cf067fbd2 100644 --- a/doc/yarp-doxygen-layout.xml +++ b/doc/yarp-doxygen-layout.xml @@ -3,7 +3,7 @@ - +