CoDocker

CoDocker

The CoDocker software is intended to generate browser viewable HTML from the solutions, projects and source code files created by the Microsoft Visual Studio CSharp software. The resulting web pages make the source code content available for reference and documentation purposes. An example of the CoDocker output can be found by viewing the CoDocker source code web pages - these were produced using CoDocker. The CoDocker software is both free and open source and is released under the terms of the MIT License.

The Main Form

CoDocker presents the configuration options and tools on tabs rather than exposing them via menus - thus making all configuration options readily available. This is something of an unconventional design - hopefully it will prove to be easy and intuitive to use once you get used to it. The CoDocker software generates HTML formatted output files, however, it is completely read-only with respect to the input files and will not modify them in any way.

The Vertical Buttons on the Right

The vertical column of buttons on the right hand side of the main form provide the major operations for the CoDocker software. These are the buttons you press to open a .sln, .csproj or .cs, file in order to convert it HTML format. Once these buttons are pressed and the input file selected, the conversion is automatic and the converted files will be output to the specified Output Directory (see below).

Open Saved Configuration

The settings used to control the appearance of the output files can be saved and recovered for later use. This button opens a previously saved configuration file.

Save Configuration

This button saves the settings to the currently open configuration file. By default this files name is Default.CoDocCfg and it is located in the same directory as the CoDocker.exe executable.

Save Configuration As

Saves the existing configuration file under a new name.

Convert .CS File to HTML

Opens a file with a .cs extension and converts it to HTML format. The file will be written to the specified Output Directory and will have the specified Output File Name Extension appended to it. The visual appearance of the HTML page will be structured according to the configuration settings currently on display.

Convert .CSPROJ File to HTML

Opens a project file with a .csproj extension and converts it to HTML format. Any .cs (and other) files referenced in this project file will also be converted to HTML and output to the Output Directory. Each file will have appropriate links which enables the viewer to move from a project to a file and back again.

Convert .SLN File to HTML

Opens a solution file with a .sln extension and converts it to HTML format. Any projects this file contains will also be converted to HTML.

The Configuration Settings Panel

The panel on the left hand side of the main CoDocker form contains the state of the configuration being used to format the HTML output.

Reset All Button

The Reset All button resets all configuration items back to the default state. All user implemented changes will be removed.

Output File Name Extension

This option enables the preferred filename extension of the output file to be chosen. The output files are always the name of the input file with the selected Output Filename Extension appended. For example, if the input filename is Test1.cs and the file extension is html then the output filename will be Test1.cs.html and it will be written to the Output Directory.

Style Sheet Options

The html files which the CoDocker software emits contain a reference to a css stylesheet which supplies the formatting. If you wish to use a different stylesheet than the default (CoDocker.css) the name of that stylesheet can be supplied in the box provided. The CoDocker software will not create the user specified stylesheet file - it will only include a reference to it in all of the output web pages. Usually a user defined stylesheet is just a user customized and renamed version of the default CoDocker.css stylesheet. Note that if the default CoDocker.css stylesheet option is chosen then that stylesheet file is created whenever HTML files are generated. Never modify the CoDocker.css stylesheet - if you wish to have a custom version - rename it first and work on that copy.

Output Directory

The Output Directory area indicates the location of the output files. Note that no subdirectories are ever created by the CoDocker software. All generated HTML files in a solution are output to the same directory. If an input file contains a subdirectory as part of the file name, then that directory becomes part of the name. For example, if a file .\myDir\test1.cs is read in as input (perhaps it was included in a project with a relative path), the output file name will be myDir.Test1.cs.html and it will be located in the specified Output Directory.

The Settings Tabs

The Settings tabs enable the page title, description, banners and footer on each output html page to be configured. Each item (banner, footer, title or description) has its own section and the output web pages for each file type (.sln, .csproj and .cs) can be configured individually if required although the default is to have all file types use the structure of the .CS file pages.

Custom Banner and Footer Content

In general, any valid HTML can be used in the banner and footer areas. In addition a number of subsitution variables are provided by the CoDocker software. These variables (which all start and end with a % character) will be replaced when the output file is created with the specified text value. For example a subsitution value of %USERNAME% will be replaced with the value of the username of the account currently running the CoDocker software.

Substitution Variables

The following values can be placed in the header, footer, title and description fields to provide runtime specified replacement values.

%CODOCKER_NAME%

The name of the CoDocker software. This is always the text CoDocker.

%CODOCKER_VERSION%

The current version number of the CoDocker software

%CODOCKER_HOME%

The home page of the CoDocker software. Currently this is http://www.OfItselfSo.com/CoDocker/CoDocker.php

%CODOCKER_ROOT%

The root website link for the CoDocker software. Currently this is http://www.OfItselfSo.com

%CODOCKERLINK%

A link to the %CODOCKER_HOME% specifying %CODOCKER_NAME% %CODOCKER_VERSION% as text.

%CURRENT_DATETIME%

The current date and time.

%INFILENAME_WITHPATH%

The name of the input file including its full path.

%INFILENAME%

The name of the input file with no path information.

%INFILENAME_NOEXT%

The name of the input file with no filename extension or path information.

%INFILEDIRECTORY%

The full path of directory the input file was found in.

%USERNAME%

The user name of the Windows account which is running the CoDocker software.

%MACHINENAME%

The Windows machine name of the account which is running the CoDocker software.

%FILETYPE%

The type of file. This translates to the word Solution if the output file is derived from a .sln file, Project if the output file is derived from a .csproj file and File if the output file is derived from any other file type.

%STYLESHEET_NAME%

The name of the stylesheet. This will be CoDocker.css if the default style sheet option is chosen.

Credits

The CSharp formatting engine is derived (from Jean-Claude Manoli's open source CSharp Formatting engine. This code is web based and was only designed to convert single .cs files. The CoDocker software contains that code (mostly unchanged except where commented) and feeds in the contents of CSharp solutions and projects so as to produce interlinked HTML documentation of all files in the solution or project.

The icon used for the CoDocker app is "Swan" part of the lovely Glass Zoo set by sirea.