HowTo Browsing the documentation while offline

From OpenFOAMWiki
Revision as of 21:47, 4 February 2008 by Unoder (Talk | contribs)

1 The idea

For those users who run OpenFOAM on their laptop that is not always connected (or pc's without internet connection or with a slow internet connection and similarly), here are some instructions for setting it up. The idea is to install a webserver on your pc (apache webserver) together with php. The following instructions worked out for OpenFOAM-1.4.1-dev and Suse:


2 Instructions for browsing the Doxygen documentation offline

1) Figure out how to install apache with php on your preferred OS (I personally used Suse YAST-tool and cannot completely remember what I chose, but if in doubt try to pick something with apache / webserver / php5 and install it).


2) Test that the webserver works: Try entering "localhost" and/or 127.0.0.1 in your favourite web-browser. You should see a webpage saying something about "This works" and/or an "advertisement for the apache server" or similar. You can be sure that something is wrong if a 404 error (webpage not found) appears. If that is the case, try running "/etc/init.d/apache2 --restart" (works for me in Suse) to shutdown httpd, re-read configuration files and start the server (daemon) up again.


3) Assuming apache/the webserver works: Go to $WM_PROJECT_DIR/doc. Then issue: "./Allwmake" unless you're sure the documentation is already there. In my case I have "Guides-a4"- and "Doxygen"- subdirectories residing here. Inside the "Doxygen"-subdirectory, there should be an "html"-subdir with a lot of files. These files are the ones we need...


4) Now you need to modify the "documentroot"/"directory" settings in your apache configuration file(s). In my case I modified a "default-server.conf" file residing in /etc/apache2 (suggestions and improvements are welcome - I don't know much about apache). You need to tell where the webserver files are locally:

DocumentRoot "/home/martin/OpenFOAM/OpenFOAM-1.4.1-dev/doc/Doxygen/html"

If in doubt, steal my configuration file below... "Options FollowSymLinks" must be enabled but you'll figure this out if everything works and you click somewhere and see an error message about some path or file that couldn't be found (or access denied or similar).


5) In order to solve the problem with Doxygen linking to C source files which it couldn't find, do this: Add a symbolic link in ~/OpenFOAM/OpenFOAM-1.4.1-dev/doc/Doxygen/html to /home/martin/OpenFOAM/OpenFOAM-1.4.1-dev/src. In linux just copy/paste this line (because apache seem to work with relative paths):

~/..../doc/Doxygen/html> ln -s /home/martin/OpenFOAM/OpenFOAM-1.4.1-dev/src ~/OpenFOAM/OpenFOAM-1.4.1-dev/doc/Doxygen/html/src


6) The content type (MIME-type) of the C-source files were in my case recognized as "text/C source file" so whenever I clicked on a source file, my browser asked me what to do with the file (download / save as etc.). I find that very annoying, so this is the fix I came up with: Add "AddType text/plain C c CPP cpp" to your apache configuration file (or steal or get inspired by my conf-file below).


7) If I didn't forgot anything and you modified your Documentroot/Directory settings properly, you should now be able to restart your apache-webserver - on my system: "/etc/init.d/apache2 --restart". Verify that you'll see some OF documentation when you enter "localhost" and/or 127.0.0.1 (not sure about if caching is a problem here - perhaps on some systems but not on mine?).




Also verify that when you enter something in the "search" field an type enter, then you should *NOT* see a popup asking whether you want to open the ".php" file or save it. I hope I didn't forget to mention anything - I don't know much about apache and/or php so please correct these instructions if something can be improved. And good luck with the off-line browsing of the documentation.


3 Example "configuration file" for apache web browser (my default-server.conf)

DocumentRoot "/home/martin/OpenFOAM/OpenFOAM-1.4.1-dev/doc/Doxygen/html" 

<directory> 
# Possible values for the Options directive are "None", "All", 
# or any combination of: 
# Indexes Includes FollowSymLinks SymLinksifOwnerMatch ExecCGI MultiViews 
# 
# Note that "MultiViews" must be named *explicitly* --- "Options All" 
# doesn't give it to you. 
# 
# The Options directive is both complicated and important. Please see 
# http://httpd.apache.org/docs-2.2/mod/core.html#options 
# for more information. 
Options FollowSymLinks 
# AllowOverride controls what directives may be placed in .htaccess files. 
# It can be "All", "None", or any combination of the keywords: 
# Options FileInfo AuthConfig Limit 
AllowOverride None 
# Controls who can get stuff from this server. 
Order allow,deny 
Allow from all 
</directory> 


# -- MARTINS MODIFICATION: THINK OF SOURCE FILES AS -- 
# -- TEXT/PLAIN OR TEXT/HTML TO AVOID DOWNLOADING THEM -- 
AddType text/plain C c CPP cpp 


# NOT SURE IF THIS IS NEEDED???? 
<ifmodule> 
# Note that the name of the user directory ("public_html") cannot simply be 
# changed here, since it is a compile time setting. The apache package 
# would have to be rebuilt. You could work around by deleting 
# /usr/sbin/suexec, but then all scripts from the directories would be 
# executed with the UID of the webserver. 
UserDir public_html 
# The actual configuration of the directory is in 
# /etc/apache2/mod_userdir.conf. 
Include /etc/apache2/mod_userdir.conf 
</ifmodule> 


# Include all *.conf files from /etc/apache2/conf.d/. 
# 
# This is mostly meant as a place for other RPM packages to drop in their 
# configuration snippet. 
# 
# You can comment this out here if you want those bits include only in a 
# certain virtual host, but not here. 
# 
Include /etc/apache2/conf.d/*.conf 

# The manual... if it is installed ('?' means it won't complain) 
Include /etc/apache2/conf.d/apache2-manual?conf 
ServerName laptop 

ServerAdmin root@laptop