DocFactory README
- Contact:
- g.schwant@gmx.de
- Date:
- 2004/05/07
- Copyright:
- Copyright (c) 2002 Dr. Gunnar Schwant (g.schwant@gmx.de). All rights reserved. See LICENSE.txt for license details.
Abstract
This is a short introduction to DocFactory. Hopefully, more documentation will be available soon.
1 What is it?
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 was built using Docutils, Python and wxPython. Many thanks to all developers!
2 System requirements
DocFactory is distributed as a subpackage of Docutils (docutils.factory). In order to run it in a Python-environment you'll need the following:
Python 2.3.2 or later (http://www.python.org).
wxPython 2.4.2.4 or later (http://wxPython.org). Be sure to get the build matching the version of Python you're using.
Docutils 0.3 or later (http://docutils.sourceforge.net). Use the CVS snapshot; improvements are being made almost daily.
3 Installation
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.
3.1 Win32
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:
cd <archive_directory_path>
Install the package:
<path_to_python.exe>\python setup.py install
3.2 GNU/Linux, Unix, MacOS X, etc.
Open a shell.
Go to the directory created by expanding the archive:
cd <archive_directory_path>
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.
4 Usage
4.1 How to start DocFactory
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.
4.2 Files
4.2.1 Create a new file
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.
4.2.2 Open an existing 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.)
4.2.3 Publish a file
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:
Dialogue Item |
Description |
---|---|
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.
4.3 Projects
If you want
to edit and publish one or more text files in the same way
to use DocFactory to edit the same files more than once or
to setup a Docutils configuration file easily
a project may be the right choice for you.
4.3.1 Setting up a project
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.
4.3.2 Adding files to a project
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.)
4.4 Editing
4.4.1 Keyboard Shortcuts
For rapid development DocFactory features Windows-style keyboard shortcuts:
Action |
Keyboard Shortcut |
---|---|
File Menu |
|
New File |
Ctrl+N |
Open File |
Ctrl+O |
Save File |
Ctrl+S |
Publish File |
F7 |
Exit Application |
Alt+X |
Edit Menu |
|
Undo |
Ctrl+Z |
Redo |
Ctrl+Y |
Cut |
Shift+Del, Ctrl+X |
Copy |
Ctrl+Ins, Ctrl+C |
Paste |
Shift+Ins, Ctrl+V |
Select all |
Ctrl+A |
Find & Replace |
Ctrl+F |
Goto line |
Ctrl+G |
Toolbox Menu |
|
Open toolbox |
F8 |
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 |
Zoom-In |
Ctrl+L |
Zoom-Out |
Ctrl+K |
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.
4.4.2 Find & Replace
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.
4.5 Toolbox
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:
Dialogue Item |
Description |
---|---|
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:
Tool Macro |
Description |
---|---|
$[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.
5 Data Storage
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
/home/fred/.docfactory
DocFactory will store its data in /home/fred/.docfactory.
6 Future Directions
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:
more stylesheets (please contribute!)
preferences dialog
[...]
Now, this should be enough for the beginning. Start playing with DocFactory, have fun, report bugs, contribute, ... Any kind of feedback is welcome.