View Issue Details

IDProjectCategoryView StatusLast Update
0001516OpenFOAM[All Projects] Bugpublic2015-02-09 19:03
ReporterwyldckatAssigned Tohenry 
PrioritylowSeverityfeatureReproducibilityN/A
Status resolvedResolutionfixed 
Product Versiondev 
Fixed in Version 
Summary0001516: Online code documetation at sourceforge.net should provide links to source code on Github
DescriptionThis feature proposition, for which fixed files are provided in attachment, relates to a long standing issue with the online code documentation for OpenFOAM. For example, in this block of text: http://foam.sourceforge.net/docs/cpp/a00100.html#details

    Detailed Description

    Foam::basicMixture.

    Source files

            basicMixture.H
            basicMixture.C

    Definition at line 50 of file basicMixture.H.


the links for the two entries for "Source files" are pointing to http://foam.sourceforge.net/src/thermophysicalModels/basic/mixtures/basicMixture/basicMixture.H - which results in a 404 error message, because the source code was not uploaded to the project's web-space at sourceforge.net.

The attached files add the ability to rely on a temporary shell environment variable "FOAM_ONLINE_REPO" for using the respective path to Github, for example, to: https://github.com/OpenFOAM/OpenFOAM-dev/tree/master - which will result in: https://github.com/OpenFOAM/OpenFOAM-dev/tree/master/src/thermophysicalModels/basic/mixtures/basicMixture/basicMixture.H

The attached files are as follows:

 - "bin/tools/doxyFilter" - has been modified to allow the optional environment variable "FOAM_ONLINE_REPO" for using as the base path for the files for source files, without affecting the true path to the local file.

 - "bin/tools/doxyFilter.sed" - has the respective modifications for supporting the script "bin/tools/doxyFilter" with this new feature.

 - "doc/Doxygen/Allwmake" - has a couple of new options, namely "-online" and "-help". The "-online" option will base itself on the shell environment variables to create the link, namely:

      export FOAM_ONLINE_REPO="https://github.com/$WM_PROJECT/$WM_PROJECT-$WM_PROJECT_VERSION/tree/master"

Additional InformationThe attached files are already taking into account the proposed bug fixes on the following issues:
 - issue #1016: http://www.openfoam.org/mantisbt/view.php?id=1016
 - issue #1512: http://www.openfoam.org/mantisbt/view.php?id=1512
TagsNo tags attached.

Activities

wyldckat

2015-02-08 18:19

updater  

doxyFilter (2,752 bytes)
#!/bin/bash
#------------------------------------------------------------------------------
# =========                 |
# \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
#  \\    /   O peration     |
#   \\  /    A nd           | Copyright (C) 2011-2015 OpenFOAM Foundation
#    \\/     M anipulation  |
#------------------------------------------------------------------------------
# License
#     This file is part of OpenFOAM.
#
#     OpenFOAM is free software: you can redistribute it and/or modify it
#     under the terms of the GNU General Public License as published by
#     the Free Software Foundation, either version 3 of the License, or
#     (at your option) any later version.
#
#     OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
#     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
#     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
#     for more details.
#
#     You should have received a copy of the GNU General Public License
#     along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
#
# Script
#     doxyFilter
#
# Description
#     pass-through filter for doxygen
#
#     Special treatment for applications/{solvers,utilities}/*.C
#     - only keep the first comment block of the C source file
#       use @cond / @endcond to suppress documenting all classes/variables
#
#     Special treatment for applications/{solvers,utilities}/*.H
#     - use @cond / @endcond to suppress documenting all classes/variables
#------------------------------------------------------------------------------

if [ "$#" -gt 0 ]
then

    realFilePath=$(echo $1 | sed -e s@^$WM_PROJECT_DIR@../../..@ )
    if [ -n "$FOAM_ONLINE_REPO" ]
    then
        filePath=$(echo $1 | sed -e s@^$WM_PROJECT_DIR@$FOAM_ONLINE_REPO@ )
    else
        filePath=$realFilePath
    fi

    # dirName=$(echo "$filePath" | sed -e 's@/[^/]*$@@' )
    dirName=${filePath%/[^/]*}
    fileName=${filePath##*/}

    awkScript=$WM_PROJECT_DIR/bin/tools/doxyFilter.awk

    case "$1" in
    */applications/solvers/*.C | */applications/utilities/*.C )
        awkScript=$WM_PROJECT_DIR/bin/tools/doxyFilter-top.awk
        ;;
#    */applications/solvers/*.H | */applications/utilities/*.H )
#        awkScript=$WM_PROJECT_DIR/bin/tools/doxyFilter-ignore.awk
#        ;;
    esac

    awk -f $WM_PROJECT_DIR/bin/tools/doxyFilter-table.awk $1 | \
    awk -f $awkScript  | \
    sed -f $WM_PROJECT_DIR/bin/tools/doxyFilter.sed \
        -e s@%realFilePath%@$realFilePath@g \
        -e s@%filePath%@$filePath@g \
        -e s@%fileName%@$fileName@g \
        -e s@%dirName%@$dirName@g
fi
#------------------------------------------------------------------------------
doxyFilter (2,752 bytes)

wyldckat

2015-02-08 18:20

updater  

doxyFilter.sed (2,554 bytes)

wyldckat

2015-02-08 18:20

updater  

Allwmake (1,351 bytes)
#!/bin/sh
cd ${0%/*} || exit 1    # Run from this directory

[ -d "$WM_PROJECT_DIR" ] || {
    echo "Error: WM_PROJECT_DIR directory does not exist"
    echo "    Check the OpenFOAM entries in your dot-files and source them."
    echo "    WM_PROJECT_DIR=$WM_PROJECT_DIR"
    exit 1
}

usage() {
    exec 1>&2
    while [ "$#" -ge 1 ]; do echo "$1"; shift; done
    cat<<USAGE

usage: ${0##*/} [OPTION]
options:
  -online    use the links to the Github repositories instead of the local source code
  -help

USAGE
    exit 1
}

# parse options
while [ "$#" -gt 0 ]
do
    case "$1" in
    -h | -help)
        usage
        ;;
    -online)
        export FOAM_ONLINE_REPO="https://github.com/$WM_PROJECT/$WM_PROJECT-$WM_PROJECT_VERSION/tree/master"
        shift
        ;;
    *)
        usage "unknown option/argument: '$*'"
        ;;
    esac
done

#------------------------------------------------------------------------------

set -x

rm -rf latex man

# remove html directory in background
mv html html-stagedRemove$$ 2> /dev/null
rm -rf html-stagedRemove$$ >/dev/null 2>&1 &

# ensure that created files are readable by everyone
umask 22
doxygen

# fix permissions (NB: '+X' and not '+x'!)
chmod -R a+rX html latex man 2>/dev/null

echo
echo "Done doxygen"
echo

# ----------------------------------------------------------------- end-of-file
Allwmake (1,351 bytes)

wyldckat

2015-02-08 18:21

updater   ~0003722

Sorry for the typo on the subject line, namely "documetation" should be "documentation".

henry

2015-02-08 23:05

manager   ~0003728

The original purpose of the source files list in the header files was to permit easier navigation of the source tree for code development, i.e. it was expected that the files would be local and editable. For this to be useful the documentation would need to be generated locally and updated regularly. Ultimately we did not find this to be very convenient and continued to use more traditional source finding methods. It was not expected that these links would be useful for browsing the remote source repository as the Doxygen files already contain HTML versions of the headers with hyperlinks. However, if people would find them useful we could upload the source tree to sourceforge for the links to work. Alternatively we could maintain github repositories of the released versions of OpenFOAM and set the links appropriately using the patches you kindly provided. Which of these two options do you think would be preferable?

For those people compiling OpenFOAM-2.3.x or OpenFOAM-dev and generating the Doxygen documentation locally what is the advantage of the source files links refering to the original files on github rather than the local clone? The advantage of refering to the local files is that you can get them to load into and editor and change them if you want to.

wyldckat

2015-02-09 10:21

updater   ~0003731

Sorry, answered not in order of the questions:

  - It hasn't been common practice in OpenFOAM's repositories to tag the first commit, but if it was, instead of the link ending in "master" it could end in the tag, e.g. "version230". This way it would not be necessary to keep a separate repository for a specific version.

  - I thought there were guidelines from SourceForge.net that you were following, in order to keep the number of files to a minimum on the rendered Doxygen code documentation section... although adding more 20000 or so files among ~130000, doesn't all that much more.

  - The reliance on Github, is that it can give us access to the raw version without having to download it directly (although it might depend on the browser being used), which possibly won't happen if the files are directly in the foam.sourceforge.net file path.

  - The other advantage of linking to the Github repository is its ability to search for words directly in the source code, in case we're looking for something that the search function in the Doxygen generated code documentation won't find.

  - The advantage of Doxygen giving access to the raw source code itself directly online is because sometimes it comes in handy to have access to the raw version. Usually helpful for comparing files from different versions, without having to download the whole source code.

  - The original purpose is still very useful, for when the code documentation is generated locally, namely for the ability to open the original source directly for editing or inspection.

henry

2015-02-09 11:45

manager   ~0003732

Now that the OpenFOAM-dev repository is public it will be tagged when versions are released and these can be refered to.

I agree that it would be good to tag the .x repository when patch releases are made and I will do this in future. If the links refer to the tags will github provide the version of the source-file relating to to that point in the repository history? If so this is an excellent idea.

I agree with you other comments and will make the changes today.

Thanks for your efforts on this.

wyldckat

2015-02-09 12:20

updater   ~0003733

Actually, only "version-2.3.1" is (was?) missing in the latest .x repositories ;)

Working example for 2.2.2, which allows browsing it online at Github: https://github.com/OpenFOAM/OpenFOAM-2.2.x/tree/version-2.2.2/src

Which is why I mentioned that the ".0" tags usually are missing, for example: https://github.com/OpenFOAM/OpenFOAM-2.2.x/releases

In addition, Github gives the maintainer the ability to add additional information to a tag (dubbed "release", as you can see in the last link), including "blobs" of binary data associated to the release.

henry

2015-02-09 15:01

manager   ~0003735

> Actually, only "version-2.3.1" is (was?) missing in the latest .x repositories ;)

OpenFOAM-2.3.x does already have the version-2.3.1 tag:

> cd OpenFOAM-2.3.x
> git tag
version-2.3.1

Do you see this tag in your clone?

henry

2015-02-09 15:04

manager   ~0003736

I just explicitly pushed the tag so you should see it now.

henry

2015-02-09 15:13

manager   ~0003737

I have also added the version-2.3.0 tag, let me know if there are any issues.

wyldckat

2015-02-09 15:17

updater   ~0003738

Yes, they are both up now: https://github.com/OpenFOAM/OpenFOAM-2.3.x/releases

But... OK, I was finding it odd that the tag for 2.3.1 was dated 17th of November, but it is in fact for the last commit before the 10th of December.

henry

2015-02-09 19:03

manager   ~0003743

Resolved by commit 24f0273b9231066f40ddce3f8036104c26dd7c03 in OpenFOAM-2.3.x
Resolved by commit ae4cdef8b5a25d898ae60d2fc4c145f08f1af0a1 in OpenFOAM-dev

Thanks Bruno

Issue History

Date Modified Username Field Change
2015-02-08 18:19 wyldckat New Issue
2015-02-08 18:19 wyldckat File Added: doxyFilter
2015-02-08 18:20 wyldckat File Added: doxyFilter.sed
2015-02-08 18:20 wyldckat File Added: Allwmake
2015-02-08 18:21 wyldckat Note Added: 0003722
2015-02-08 23:05 henry Note Added: 0003728
2015-02-09 10:21 wyldckat Note Added: 0003731
2015-02-09 11:45 henry Note Added: 0003732
2015-02-09 12:20 wyldckat Note Added: 0003733
2015-02-09 15:01 henry Note Added: 0003735
2015-02-09 15:04 henry Note Added: 0003736
2015-02-09 15:13 henry Note Added: 0003737
2015-02-09 15:17 wyldckat Note Added: 0003738
2015-02-09 19:03 henry Note Added: 0003743
2015-02-09 19:03 henry Status new => resolved
2015-02-09 19:03 henry Resolution open => fixed
2015-02-09 19:03 henry Assigned To => henry