Name	Last modified	Size

Parent Directory		-
NOTES.html	2021-07-07 11:50	21K
LICENSE.html	2021-07-07 11:50	21K
doc/	2021-04-16 16:06	-
setup.py	2018-06-17 08:52	1.2K
factory/	2018-06-17 08:52	-
docutils.conf	2018-06-17 08:52	257
docfactory2exe.py	2018-06-17 08:52	285
docfactory.py	2018-06-17 08:52	148
docfactory.ico	2018-06-17 08:52	3.6K
createdoc.py	2018-06-17 08:52	629
NOTES.txt	2018-06-17 08:52	1.3K
LICENSE.txt	2018-06-17 08:52	1.5K

DocFactory README

Author:: Dr. Gunnar Schwant
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.

[4]

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

Index of /sandbox/gschwant/docfactory

DocFactory README