Write

This module is the mediator for all writing-related classes and modules

Writing the documentation files

From the given file a .rst file will be created if it contains an antiweb start() directive. The following function is called for the creation of the documentation files.

write(working_dir, input_file, options)

Creates the corresponding documentation file.

Parameters:
  • working_dir – Current working directory.
  • input_file – Contains the absolute path of the currently processed file.
  • options – Commandline options.
  • print_message – Indicates whether a log message should be printed for the processed input file.
Returns:

the absolute path of the generated output file or None if an error occurred

Before the input file is processed the name of the output file has to be computed. How the output file name is created depends on the different commandline options. When there is no output option given the output file name is created in the following way:

Input File Output File
C:\antiweb\testing.cs C:\antiweb\testing.rst
C:\antiweb\testing.rst C:\antiweb\testing_docs.rst 
def write(working_dir, input_file, options, print_message=True):

    #options.output is either an absolute path or None
    output = options.output
    recursive = options.recursive

    if not output:
        out_file = _create_out_file_name(working_dir, input_file)

If there is an output given, we have to distinguish between the recursive and non-recursive option. When the recursive option is used in combination with the output option, the output parameter is treated as the documentation directory:

Commandline Current Directory Output File
C:\antiweb\ -r -o report.rst C:\dir C:\dir\report.rst\file.rst
C:\antiweb\ -r -o report C:\dir C:\dir\report\file.rst
C:\antiweb\ -r -o C:\report C:\dir C:\report\file.rst
C:\antiweb\ -r -o \..\report.rst C:\dir C:\report.rst\file.rst 
else:
    if recursive:
        #The output parameter is treated as a directory.
        directory = output
        out_file = _create_out_file_name(directory,input_file)

When the output option is used without the recursive option the output file name is computed in the following way:

Commandline Current Directory Output File
C:\antiweb\testing.cs -o report.rst C:\dir C:\dir\report.rst
C:\antiweb\testing.cs -o report C:\dir C:\dir\report\testing.rst
C:\antiweb\testing.cs -o \..\report C:\dir C:\dir\report\testing.rst
C:\antiweb\testing.cs -o report\report.rst C:\dir C:\dir\report\report.rst
C:\antiweb\testing.cs -o C:\report\report.rst C:\dir C:\report\report.rst 
    else:
        #Get the file extension from output parameter
        file_extension = os.path.splitext(output)[1]

        if file_extension:
            #If there is a file extension the last part of the output parameter is treated as the output file name.
            path_tokens = os.path.split(output)
            directory = path_tokens[0]
            file_name = path_tokens[1]

            out_file = os.path.join(directory, file_name)
            out_file = os.path.abspath(out_file)
        else:
            #If there is no file extension the whole output parameter is treated as the report directory.
            directory = output
            out_file = _create_out_file_name(directory, input_file)

#Create the documentation directory. If it can't be created the program exits.
_create_doc_directory(out_file)

Now the input file is processed and the corresponding documentation file is created. If processing is successful, ‘’could_write’’ is set to ‘’True’‘.

could_write = _process_file(input_file, out_file, options.token, options.warnings)

generated_file = None

if could_write:
    #processing was successful
    generated_file = out_file

if print_message:
    log_message = create_write_string(input_file, generated_file)
    print("\n"+log_message)

return generated_file
_create_out_file_name(working_dir, input_file)

Computes the absolute path of the output file name. The input file name suffix is replaced by ”.rst”. If the input file name ends with ”.rst” the string “_docs” is added before the suffix. The output file name consists of the combination of the directory and the input file name.

Parameters:
  • directory – The absolute path of the documentation directory.
  • input_file – The absolute path to the file which should be processed.
Returns:

The absolute path of the output file.
Directory Input_File_Name Output_File_Name
C:\antiweb\doc C:\antiweb\testing.py C:\antiweb\doc\testing.rst
C:\antiweb\ C:\antiweb\testing.py C:\antiweb\testing.rst
C:\antiweb\doc C:\antiweb\testing.rst C:\antiweb\doc\testing_docs.rst
C:\antiweb\doc testing.py C:\antiweb\doc\testing.rst 
def _create_out_file_name(directory, input_file):

    docs = "_docs"
    rst_suffix = ".rst"
    out_file_path = os.path.splitext(input_file)[0]

    if input_file.endswith(rst_suffix):
        out_file_path =  out_file_path + docs

    out_file_path =  out_file_path + rst_suffix

    out_file_name = os.path.split(out_file_path)[1]

    #If directory contains an absolute path, the working directory is ignored.
    out_file = os.path.join(directory, out_file_name)
    out_file = os.path.abspath(out_file)
    return out_file
_create_doc_directory(out_file)

Creates the documentation directory if it does not yet exist. If an error occurs, the program exits.

Parameters:out_file – The path to the output file. 
def _create_doc_directory(out_file):
    try:
        out_file_directory = os.path.split(out_file)[0]
        if not os.path.exists(out_file_directory):
            os.makedirs(out_file_directory)
    except IOError:
        logger.error("\nError: Documentation Directory: %s could not be created", out_file_directory)
        sys.exit(1)
_process_file(in_file, out_file, token, warnings)

If no output name was declared, the input name will be given.

Parameters:
  • in_file – The path to the input file.
  • out_file – The path to the output file.
  • token – Passes on the tokens which the user set.
Returns:

The boolean could_write indicates if the file could be written.

 
def _process_file(in_file, out_file, token, warnings):

#The output text will be written in the output file. If there is an output text, the function returns could_write as True.

    could_write = False
    try:
        text_output = generate(in_file, token, warnings)
        if text_output:
            with open(out_file, "w") as f:
                f.write(text_output)
            could_write = True
    except WebError as e:
        logger.error("\nErrors:")
        for l, d in e.error_list:
            logger.error("  in line %i(%s): %s", l.index+1, l.fname, d)
            logger.error("      %s", l.text)

    return could_write
create_write_string(could_write, input_file, created_file)

Creates a string message based on the value of the created_file.

Parameters:
  • input_file – Contains the absolute path of the currently processed file.
  • created_file – Contains the absolute path of the created documentation file.
Returns:

A created string based on the value of created_file.

 
def create_write_string(input_file, created_file):

    if created_file:
        out_string = "Generated " + created_file + " from: " + input_file
    else:
        out_string = "Could not generate documentation file for: " + input_file

    return out_string