|Author:||Dr. Gunnar Schwant|
|Copyright:||Copyright (c) 2002 Dr. Gunnar Schwant (firstname.lastname@example.org). All rights reserved. See LICENSE.txt for license details.|
This is a short introduction to DocFactory. Hopefully, more documentation will be available soon.
DocFactory is a kind of integrated publishing environment for documentation, tied to Docutils. In fact, the intention of DocFactory is to be a GUI for Docutils. At present it can be used to edit a set of one or more reStructuredText files simultaneously and publish them as HTML. Support for other markups and output formats is planned for future releases; see Future Directions.
DocFactory is distributed as a subpackage of Docutils (docutils.factory). In order to run it in a Python-environment you'll need the following:
The first step is to expand the .tar.gz or .tgz archive.1 It contains a distutils setup file "setup.py". OS-specific installation instructions follow.
Open a DOS box (Command Shell, MSDOS Prompt, or whatever they're calling it these days).
Go to the directory created by expanding the archive:
Install the package:
<path_to_python.exe>\python setup.py install
Open a shell.
Go to the directory created by expanding the archive:
Install the package:
python setup.py install
If the python executable isn't on your path, you'll have to specify the complete path, such as /usr/local/bin/python. You may need root permissions to complete this step.
To create and browse the documentation of DocFactory please run the script createdoc.py. This script converts all the .txt-files of the tarball to .html-files and opens doc/index.html with your default webbrowser.
After successful installation you'll find "docfactory.py" in the scripts-directory of your Python environment. Run this file in the same way as you do it with any other Python-program on your system. The main window will appear.
Type Ctrl+N to create a new text file. You will be asked for a location and title of the new file. Afterwards the file will be created, added to the tree on the left and loaded it into the editor. As you will notice the title has been inserted at the top of the file.
To open an already existing text file simply type Ctrl+O and select the file. It will be added to the tree and loaded into the editor. Moreover, you can open a file from the command-line if you specify the file as first parameter. A command like python [Scripts-directory]/docfactory.py [<file>] should launch DocFactory and open the file for editing. (Of course, this command depends on your system. For example:
C:\>python Python22\Scripts\docfactory.py temp\test.txt
works on my windows machine. In particular, the Python executable has to be on your path.)
To "publish" a file means to process the file into useful formats, such as HTML, XML or TeX.
A file which has been loaded into the editor can be published by pressing F7. You will be asked for a docutils-writer, an output-directory and a filename:
|Docutils-Writer||The docutils-writer which will be used for publishing.|
|Output-Directory||The directory where the output-file will be created.|
|Output-File||The name of the output-file. (Existing files will be overwritten!)|
Press "OK" to start the publisher.
If you choose the HTML-writer the HTML-file will be displayed on DocFactory's HTML-viewer-page as soon as it is finished. Please note that this viewer does support stylesheets on Windows platforms only (including Windows 95, 98, ME, 2000, NT, XP). On any other platform you will have to check the final layout with a webbrowser of your choice (which hopefully does support stylesheets). Click on "View In Browser" to open the file with your system's default webbrowser.
Please note that publishing happens in a standard Docutils way and can be customized by setting up Docutils configuration files.2
If you want
a project may be the right choice for you.
To setup a project select "Project -> New". The Project Settings dialog will appear. Within this dialog you set the output-directory and a title for your project. The output-directory is the default directory for any output-files, that will be created.
If you press the "Edit docutils.conf"-button, DocFactory will display a dialog, which allows you to edit the docutils.conf-file, which resides in the output-directory. (If there is no such file in the output-directory, DocFactory will create one for you.) Please have a closer look at the Docutils documentation on configuration files, if you are not familiar with docutils.conf-files.3
Press the "OK"-buttons to finish the setup. The project appears as part of the tree on the left.
In order to create a new file within a project or add an existing file to a project simply activate the project's item in the tree on the left (double-click) and press Ctrl+N or Ctrl+O. The behaviour is like this: If a project is active any file which is created and/or opened will be added to the active project. (If no project is active files will be created/opened outside of projects.)
For rapid development DocFactory features Windows-style keyboard shortcuts:
|Find & Replace||Ctrl+F|
|Further editing commands|
|Cursor movement||Arrow keys or mouse|
|Beginning of line||Home|
|End of line||End|
|Beginning of buffer||Ctrl+Home|
|End of the buffer||Ctrl+End|
|Select text||Hold down Shift while moving the cursor|
Right mouse-click brings up a popup-dialog with most of the above editor commands. Moreover, you can use the mouse to move selected text.
The "Find & Replace"-dialog was introduced with DocFactory release 0.2 and is special in the sense that it uses regular expression syntax for searching as defined by Python's re-module. This offers a great deal of flexibility in searching. For example: Searching for Fred|Ted will search the file for appearances of Fred as well as for appearances of Ted. However, it also requires a certain kind of familiarity with Python's regular expression syntax. For example: In order to find appearances of C:\temp\test.txt you will have to search for C:\\temp\\test.txt.
The Toolbox allows you to run operating system commands from within DocFactory. In the menu bar select "Toolbox -> Configure" to set up your personal toolbox. Press the "+"-button to add a new tool. You will be asked for a name, a command and an initial directory:
|Name||An individual name of the tool.|
|Command||The operating system command which will be executed when you run the tool.|
|Initial Directory||The initial working directory of the tool.|
Command and initial directory of a tool may include tool macros which will be replaced on tool-execution as follows:
|$[FilePath]||The full pathname of the active file.|
|$[FileDir]||The drive and directory of the active file.|
|$[FileName]||The filename of the active file.|
|$[FileBase]||The filename without the extension.|
|$[ProjectDir]||The output-directory of the active project.|
To launch a tool select "Toolbox -> Open..." or press F8.
DocFactory uses the Python's ConfigParser-module to store any information about projects, tools, etc. which has to be saved between runs.4 As default the data storage file is located in the package's directory.5 The default name of the file is docfactory.dat.
You can change the name and location of the data storage file by creating a file called conf.pth in the package's directory. This file should consist of one line only which contains the complete data storage path. For example: If the first line of conf.pth is
DocFactory will store its data in /home/fred/.docfactory.
Future releases of DocFactory will support any markup and output formats which are supported by Docutils. Some other useful things will be implemented as well. For example:
Now, this should be enough for the beginning. Start playing with DocFactory, have fun, report bugs, contribute, ... Any kind of feedback is welcome.
|||The latest DocFactory-tarball is available at http://docutils.sf.net/docfactory-snapshot.tgz.|
The storage file has a [docfactory_project: <name of project>] section for each project. (<name of project> is replaced by the project's name.) Each section header is followed by two name=value entries: One for all project files and one for the outputdirectory. For example: The section for a project called project_01 which consists of two files C:\file1.txt, C:\file2.txt and whose output-directory is C:\project1 looks like this:
[docfactory_project: project_01] files=C:\file1.txt;C:\file2.txt outputdirectory=C:\project1