Started adding documentation using sphinx
This commit is contained in:
Veronica K. B. Olsen
@@ -1,6 +1,10 @@
|
||||
# Setup
|
||||
MANIFEST
|
||||
dist/
|
||||
deploy/
|
||||
|
||||
# Documentation
|
||||
docs/build/
|
||||
|
||||
# Python Temp
|
||||
__pycache__
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
SOURCEDIR = source
|
||||
BUILDDIR = build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
@@ -0,0 +1,35 @@
|
||||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=source
|
||||
set BUILDDIR=build
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.http://sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
|
||||
|
||||
:end
|
||||
popd
|
||||
@@ -0,0 +1,173 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# This file does only contain a selection of the most common options. For a
|
||||
# full list see the documentation:
|
||||
# http://www.sphinx-doc.org/en/master/config
|
||||
|
||||
# -- Path setup --------------------------------------------------------------
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath("."))
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = "novelWriter"
|
||||
copyright = "2018-2019, Veronica Berglyd Olsen"
|
||||
author = "Veronica Berglyd Olsen"
|
||||
|
||||
# The short X.Y version
|
||||
version = "0.3.1"
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = "0.3.1"
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
#
|
||||
# needs_sphinx = "1.0"
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ["_templates"]
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
#
|
||||
# source_suffix = [".rst", ".md"]
|
||||
source_suffix = ".rst"
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = "index"
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = []
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = None
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = "classic"
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#
|
||||
# html_theme_options = {}
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ["_static"]
|
||||
|
||||
# Custom sidebar templates, must be a dictionary that maps document names
|
||||
# to template names.
|
||||
#
|
||||
# The default sidebars (for documents that don"t match any pattern) are
|
||||
# defined by theme itself. Builtin themes are using these templates by
|
||||
# default: ``["localtoc.html", "relations.html", "sourcelink.html",
|
||||
# "searchbox.html"]``.
|
||||
#
|
||||
# html_sidebars = {}
|
||||
|
||||
|
||||
# -- Options for HTMLHelp output ---------------------------------------------
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = "novelWriterdoc"
|
||||
|
||||
|
||||
# -- Options for LaTeX output ------------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ("letterpaper" or "a4paper").
|
||||
#
|
||||
# "papersize": "letterpaper",
|
||||
|
||||
# The font size ("10pt", "11pt" or "12pt").
|
||||
#
|
||||
# "pointsize": "10pt",
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#
|
||||
# "preamble": "",
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#
|
||||
# "figure_align": "htbp",
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, "novelWriter.tex", "novelWriter Documentation",
|
||||
"Veronica Berglyd Olsen", "manual"),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for manual page output ------------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
(master_doc, "novelwriter", "novelWriter Documentation",
|
||||
[author], 1)
|
||||
]
|
||||
|
||||
|
||||
# -- Options for Texinfo output ----------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, "novelWriter", "novelWriter Documentation",
|
||||
author, "novelWriter", "One line description of project.",
|
||||
"Miscellaneous"),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for Epub output -------------------------------------------------
|
||||
|
||||
# Bibliographic Dublin Core info.
|
||||
epub_title = project
|
||||
|
||||
# The unique identifier of the text. This can be a ISBN number
|
||||
# or the project homepage.
|
||||
#
|
||||
# epub_identifier = ""
|
||||
|
||||
# A unique identification for the text.
|
||||
#
|
||||
# epub_uid = ""
|
||||
|
||||
# A list of files that should not be packed into the epub file.
|
||||
epub_exclude_files = ["search.html"]
|
||||
@@ -0,0 +1,35 @@
|
||||
novelWriter Documentation
|
||||
=========================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
projects
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
novelWriter is a simple multi-document plain text editor using a modified
|
||||
markdown syntax to apply simple formatting. Additional features are available
|
||||
through special meta data commands. These make it possible to generate an
|
||||
overview of the entire novel project and how the various files are
|
||||
interconnected.
|
||||
|
||||
The user interface is intended to be as minimalistic as practically possible,
|
||||
and most features are accessible through the menu and through keyboard
|
||||
shortcuts. The colour scheme of the user interface can be modified with various
|
||||
themes, and new themes are fairly straight forward to add. They are separated
|
||||
into gui and syntax themes, and can be found in the themes folder in the source
|
||||
code.
|
||||
|
||||
The tree view has various sections for the various types of supporting files
|
||||
that the User may want to add to the project. The novel itself lives under its
|
||||
own root folder, and export features are in the process of being added. These
|
||||
will include HTML, open document and PDF via LaTeX.
|
||||
|
||||
Indices and Tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
@@ -0,0 +1,115 @@
|
||||
Novel Projects
|
||||
==============
|
||||
|
||||
A novelWriter project requires a dedicated folder for storing its files.
|
||||
See the Technical Information section for further details.
|
||||
|
||||
A new project can be created from the Project menu by selecting :menuselection:`Project --> New Project`.
|
||||
A list of recently opened projects is also maintained and can be selected from the menu.
|
||||
|
||||
The project specific settings are available in :menuselection:`Project --> Project Settings`.
|
||||
See further details below.
|
||||
|
||||
Project Structure
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Projects are structured into a set of root folders, visible in the left side tree view panel.
|
||||
|
||||
The core novel files go into a root folder of type Novel.
|
||||
Other supporting files go into root folders of types Plot, Characters, Locations, Timeline, Objects or Custom.
|
||||
These other root folder types are intended for your notes on the various elements of your story.
|
||||
Using these are of course entirely optional.
|
||||
|
||||
* **Novel:** The root folder of all text that goes into the final novel.
|
||||
This class of files have other rules and features than other files in the project.
|
||||
See the Novel Structure section for more details.
|
||||
* **Plot:** This is the root folder where main plots can be outlined.
|
||||
It is optional, but adding at least dummy files can be useful in order to generate the timeline view.
|
||||
* **Characters:** Character files go in this root folder.
|
||||
These are especially important if one wants to use the timeline view to see which character appears where and which part of the story is told from a specific character's point-of-view.
|
||||
* **Locations:** Location is for various scene locations that one wants to track in the timeline view if that applies to the story.
|
||||
* **Timeline:** If the story jumps in time within the same plot, this class of files can be used to track this.
|
||||
* **Objects:** Important objects in the story can be tracked here, and connected to the timeline as well.
|
||||
* **Custom:** The custom root folder can be used for tracking anything else not covered by the above options.
|
||||
|
||||
Deleted files will be moved into a special "Trash" root folder.
|
||||
Currently, these files cannot be permanently deleted from the project.
|
||||
|
||||
Orphaned Documents
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In the event the editor crashes or otherwise exits without saving the project state, files that have been added to the project tree and are saved to disk will appear in a special "Orphaned Items" root folder next time the application is started.
|
||||
These orphaned files will not have any meta data associated with them, so the title and other information has to be set again, and the files moved back to the correct location in the project.
|
||||
Using Project Folders
|
||||
|
||||
Folders, aside from root folders, have no structural significance to the project. They are there purely as a way for the user to organise the files in meaningful sections and to be able to close them in the tree view. When processing the files in the novel, the folders are ignored.
|
||||
|
||||
Project Settings
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
The project settings can be accessed from the :menuselection:`Project --> Project Settings` menu entry.
|
||||
This will open a dialog box.
|
||||
|
||||
Settings Tab
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The Settings tab holds the project title and author settings.
|
||||
Working Title can be set to a different title than the Book Title.
|
||||
The difference between them is simply that the Working Title is used for the GUI (main window title) and when the export features are added can optionally be printed to the cover sheet.
|
||||
The Book Title, on the other hand, will only be printed to the title page on export.
|
||||
|
||||
The Book Authors text box takes one author per line.
|
||||
The line breaks matter in that this is converted to a list for later correct formatting.
|
||||
|
||||
Status Tab
|
||||
~~~~~~~~~~
|
||||
|
||||
Each file of type NOVEL can be given a status level, signified by a coloured icon.
|
||||
These are purely there for the user's convenience, and you are not required to use them for any other feature to work.
|
||||
The intention is to use this list to set what stage of writing you are on, although you can in principle make them whatever you want.
|
||||
|
||||
Note that status levels currently in use by a file cannot be deleted.
|
||||
|
||||
Importance Tab
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Each file of types PLOT, CHARACTER, WORLD, TIMELINE, OBJECT or CUSTOM can be given an importance level, signified by a coloured icon like for status level.
|
||||
These are also purely there for the user's convenience, and you are not required to use them for any other feature to work.
|
||||
The intention is to use this list to set how important the character, plot element, or otherwise, is for the story.
|
||||
Again, these can in principle be used for whatever you want.
|
||||
|
||||
Note that importance levels currently in use by a file cannot be deleted.
|
||||
|
||||
Auto-Replace Tab
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
A set of automatically replaced keywords can be added in this tab.
|
||||
The keywords in the left column wile be replaced by the text in the right column when documents are opened in the viewer.
|
||||
This will also be applied to exports when the feature is added.
|
||||
|
||||
Note that a keyword cannot contain any spaces.
|
||||
The angle brackets are added by default, and when used in the text are a part of the keyword to be replaced.
|
||||
This is to ensure that parts of the text isn't unintentionally replaced by the content of the list.
|
||||
|
||||
Writing Files
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
New document files can be created from the Document menu, or by pressing Ctrl+N while in the tree view pane.
|
||||
This will create a new, empty file, and open the item settings dialog where the filename and various other settings can be set.
|
||||
This dialog can also be opened again later from either the menu, :menuselection:`Project -> Edit` item, or by pressing Ctrl+E or F2 with the item selected.
|
||||
|
||||
The different classes of documents have some restrictions.
|
||||
|
||||
Backup
|
||||
^^^^^^
|
||||
|
||||
An automatic backup system is built into novelWriter.
|
||||
In order to use it, a backup path to where the backups are to be stored needs to be provided in :menuselection:`Tools --> Preferences`.
|
||||
Backups can be run automatically when a project is closed, which also implies it is run when the application is closed.
|
||||
Backups are date stamped zip files of the entire project folder.
|
||||
|
||||
The backup feature, when configured, can also be run manually from the Tools menu.
|
||||
|
||||
For the backup to be able to run, the Working Title must be set in Project Settings.
|
||||
This value is used to generate the file name.
|
||||
It is also possible to dissable automated backup for a given project in its project settings.
|
||||
Reference in New Issue
Block a user