Sphinx Based Documentation for The Open Microscopy Environment

Getting Started With Sphinx

Initial setup

Sphinx

Sphinx depends on the sphinx-build Python script. As such, it can be installed on any system with a working Python installation and PIP. On Windows, make sure that the Scripts directory under the Python installation directory (e.g. C:\Python26\Scripts) is configured in your PATH. On OS X/Linux, sphinx-build has to be accessible from the command line.

The Sphinx documentation system can be obtained by issuing:

pip install Sphinx

Most Linux distributions will also provide it in a python-sphinx package (or similar).

Ant

You will also need ant for building the documentation. This can be installed on Mac OSX by using homebrew:

brew install ant

Structure and organization

The OME documentation is organized into multiple folders:

the OMERO documentation is under the omero folder,
the OME Contributing Developer documentation has been migrated to

ome-contributing, * the shared configuration and themes are under the common folder.

The structure of each documentation folder follows the Sphinx system guidelines. A quick overview:

source *.rst files with reST markup live in the root of the folder and under subfolders,
images/screenshots are placed under images,
downloadable files are placed under downloads,
compiled output is placed in _build,
compiled visual themes are automatically placed in _static,
Sphinx configuration is held in conf.py,
goals for make and make.bat are held in Makefile.

A reference of reStructuredText (reST) is available at https://thomas-cokelaer.info. It is recommended to familiarise oneself with the syntax outlined there.

A tutorial covering Sphinx, which enhances working with reST documents, can be found at http://sphinx.pocoo.org.

Building the documentation

The documentation may be built with make or ant. Note that ant requires ant-contrib to be on the classpath.

Basic build commands

To build a set of documentation, first move to the documentation folder. To build the OMERO documentation:

cd omero/

To clean the build directory of any previous builds, use one of:

make clean
ant clean

To build the documentation locally in the form of HTML pages, use one of:

make html
ant html

To check the links (internal and external) of the documentation, use one of:

make linkcheck
ant linkcheck

By default, make will build the documentation locally in the form of HTML pages.

Top-level build command

The top-level directory Makefile also defines targets for building both the OMERO and Contributing sets of documentation at once.

To clean the build directories of any previous builds, use one of:

make clean
ant clean

To build the sets of documentation locally in the form of HTML pages, use one of:

make html
ant html

By default, running make will build the documentation locally in the form of HTML pages.

Makefile options

Additional options for sphinx-build can be passed using the SPHINXOPTS variable. The -W option turns all warnings into errors:

SPHINXOPTS=-W make clean html
SPHINXOPTS=-W ant clean html

Release number

The release number of the OMERO documentation is UNKNOWN by default. To modify this value set the environment variable OMERO_RELEASE e.g.:

cd omero && OMERO_RELEASE=5.4.0 make clean html
cd omero && OMERO_RELEASE=5.4.0 ant clean html

This variable needs to be set to build all the version-dependent content used in the system administrator documentation correctly.

The Contributing Developer documentation has the release version removed as the intention is to update these files as and when necessary, so that they always reflect our current practices.

Zip bundles

To build the documentation as a zipped bundle, use:

ant zip

By default, running ant will build as a zipped bundle.

From the top level directory:

OMERO_RELEASE=5.4.0 ant zip -Domero.release="5.4.0"

will generate the HTML documentation for OMERO and Contributing and bundle just the OMERO documentation into an OMERO.doc-5.4.0.zip under omero/_build.

From omero directory:

OMERO_RELEASE=5.4.0 ant zip -Domero.release="5.4.0"

will generate the HTML documentation for OMERO and create an OMERO.doc-5.4.0.zip under omero/_build.

Auto-generated content

Some parts of the OMERO documentation are auto-generated from the OMERO deliverables (e.g. templates, command-line output...). This auto-generation is usually done via Continuous Integration builds. To generate these components manually, download the OMERO.server and run the auto-generation script as:

WORSKSPACE=/path/to/OMERO/deliverables ./omero/autogen_docs

Conventions Used

Part of the conventions used here is based on work by Benoît Bryon.

File names

reST source file names should carry the rst suffix and use lowercase alphanumeric characters and the - (minus) symbol.

Indentation

Most reST directives do not need indentation, unless contents or options have to be supplied. For consistency, please use 4 space indentation whenever needed. Do not use indentation for the start of directives (start them at the edge of the new line). Any content under a reST directive has to be indented the same way as the options.

Example:

.. toctree::
    :maxdepth: 2

    Some content here...

Line wrapping

reST source files should use 78 lines for wrapping text. Please consult the manual of your favourite text editor to see how to switch on text wrapping.

Blank lines

Two new lines should be put before top-lined, top-level section names, i.e. before H1 and H2. One new line in any other case.

Example:

###############
Part title (H1)
###############

Introduction text.
(blank)
(blank)
******************
Chapter title (H2)
******************

Title headings

Every reST source file should begin with an H2 (level two) title. H1 titles are reserved for the index files (index.rst).

The following symbols should be used to create headings:

# with top line for parts
* with top line for chapters
= for sections
- for subsections
^ for subsubsections
" for paragraphs

Example:

###############
Part Title (H1)
###############

H1 only in indexes.


******************
Chapter Title (H2)
******************

Sample file content.


********************
Another chapter (H2)
********************

Section title (H3)
==================

Subsection title (H4)
---------------------

Subsubsection title (H5)
^^^^^^^^^^^^^^^^^^^^^^^^

Paragraph title (H6)
""""""""""""""""""""

And some text.

Page labels and references

Every page can be uniquely referenced using the sphinx doc directive. Like other directives, you can use the absolute file path, i.e. relative to the top-level directory: :doc: `/path/name-of-the-page` or :doc: `link to my page </path/name-of-the-page>`.

Only when a good reason exists, a document can also start with a label:

.. _page-label:


Title Of The Page
=================

Use of labels to refer to whole files is discouraged. References to labels above tables and images are encouraged. The :ref: Sphinx role is advised over standard reST links, as it works across files and reference names are automatically generated (e.g. from caption of an image).

Images vs. figures

reST allows for two types of image embedding: using the image and figure directive. It is recommended to use the latter, as legends and captions can be added easier.

All images referenced in a reST document shall be placed in an images folder in the top-level directory of the documentation.

Please do not use relative (../../../images/foo.jpg) paths to refer to images. Sphinx does a good job at creating paths, so one can use /images/foo.jpg

Tables

Please do not use tables for collections of links and figures, and leave them solely for use as actual tables. While it can be used in HTML to shoehorn content into boxes, it does not work too well for other output.

Big tables (typically wider than 50 characters) should be managed as external files using the comma-separated values (CSV) format. These tables can then be included in the documentation with the csv-table directive. If tables are saved using the tab-separated values (TSV) format use the delim option to set the table delimiter to tab e.g.:

.. csv-table::
    :widths: 20 80
    :header-rows: 1
    :file: searchfieldnames.tsv
    :delim: tab

Substitutions, aliases and hyperlinks

reST allows for using substitutions in cases where a piece of markup is used more than once, e.g.:

Please visit Python.org_

...

.. _Python.org: https://www.python.org

If a hyperlink appears only once, please use anonymous, "one-off" hyperlinks (two underscores):

`RFC 2396 <https://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC
2732 <https://www.rfc-editor.org/rfc/rfc2732.txt>`__ together
define the syntax of URIs.

Finally, please avoid using here as the hyperlink name, as in:

(...) go `here <http://www.google.com>`_.

Common markups

Please try to follow the rules outlined in Inline Markup. This allows for improving the semantics of the document elements.

Notes should be formatted using the note directive: .. note::
Definition lists can be created and cross-referenced using the glossary directive: .. glossary::. Each definition can be referenced anywhere in the documentation using the :term: role and an entry will be added for every term in the generated index.
References to external documentation can be formatted using: .. seealso::
Menu selections should be marked using the appropriate role: :menuselection: `Start --> Programs`
Environment variables should be formatted using the :envvar: role. This role will add an entry for the variable in the generated index.
CLI Commands can be formatted using the following role: :omerocmd: `admin start` This role will render as omero admin start and add an entry for the command in the generated index.
Other commands should be formatted using the literal markup: :literal: `command` or double back quoted markup
Configuration properties for OMERO.server and OMERO.web are marked using the custom property directive and can be cross referenced e.g. using :property: `omero.data.dir`
Other useful inline markups include: :option: and :guilabel:
Do not use inline highlighting or other markups in headings or subheadings

Global substitutions

Some substitutions have been implemented using rst_epilog in conf.py. They can be used in all pages of the documentation.

Hyperlinks

The table below lists targets for common hyperlinks.

Target name	Link
Python	https://www.python.org
Matplotlib	https://matplotlib.org/
Pillow	https://pillow.readthedocs.org
Hibernate	http://www.hibernate.org
ZeroC	https://zeroc.com
Ice	https://zeroc.com
Jenkins	https://jenkins.io/
roadmap	https://trac.openmicroscopy.org/ome/roadmap
Open Microscopy Environment	https://www.openmicroscopy.org
Glencoe Software, Inc.	https://www.glencoesoftware.com/
PyPI	https://pypi.org

Abbreviations

The table below lists substitutions for common abbreviations. These substitutions use the :abbr: Sphinx role meaning they are shown as tool-tip in HTML.

Name	Abbreviation	Explanation
\|SSH\|	SSH	Secure Shell
\|VM\|	VM	Virtual Machine
\|OS\|	OS	Operating System
\|SSL\|	SSL	Secure Socket Layer
\|HDD\|	HDD	Hard Disk Drive
\|CLI\|	CLI	Command Line Interface

OMERO page references

The table below lists substitutions that can be used to create references to sections of the OMERO documentation.

Name	Path
\|OmeroPy\|	developers/Python
\|OmeroCpp\|	developers/Cpp
\|OmeroJava\|	developers/Java
\|OmeroMatlab\|	developers/Matlab
\|OmeroApi\|	developers/Modules/Api
\|OmeroWeb\|	developers/Web
\|OmeroClients\|	developers/GettingStarted
\|OmeroGrid\|	sysadmins/grid
\|OmeroSessions\|	developers/Server/Sessions
\|OmeroModel\|	developers/Model
\|ExtendingOmero\|	developers/ExtendingOmero
\|BlitzGateway\|	developers/Python

For the most up-to-date list, please consult conf.py (section rst_epilog).

Common URLs

Some URLs are widely used across the OME documentation. Using the Sphinx extlinks extension, a dictionary of aliases to base URLs has been defined for the following:

image.sc forum: :imagesc: `tag <tag>`
Trac tickets: :ticket: `3442`, displayed as <a>#3442</a>
Snapshots: :snapshot: `omero/myzip.zip`
Website pages: :omero: `OMERO <>`
Downloads: :downloads: `OMERO downloads <>`

For the most up-to-date list, please consult conf.py (section extlinks). Note that there are separate conf.py files for each set of documentation, as well as a shared one under common/.

Source code links

Links to the OMERO source code hosted on Github can be created using the source alias for single files, e.g. :source: `etc/grid/default.xml` or the sourcedir alias for directories, e.g. :sourcedir: `etc`.

By default, these links will point at the code under the develop branch or https://github.com/ome/openmicroscopy. To specify a specific fork and/or branch, set the SOURCE_USER and SOURCE_BRANCH environment variables, e.g.:

SOURCE_USER=sbesson SOURCE_BRANCH=my_branch make clean html
SOURCE_USER=sbesson SOURCE_BRANCH=my_branch ant clean html

Jenkins links

Links to the continuous integration server can be created using the jenkins alias for the main server, e.g. :jenkins: `Jenkins server <>`, the jenkinsjob alias for a given job, e.g. :jenkinsjob: `OMERO-4.4` or the jenkinsview alias for a given view, e.g. :jenkinsview: `4.4`.

Mailing-list links

For the legacy OME mailing lists, to point at specific discussion threads, two aliases have been defined, ome-users and ome-devel, e.g. :ome-users:`ome-users thread <2009-June/001839.html>`.

Inclusion of content

When a specific type of content (e.g. code snippet) repeats itself among many pages, it is advised to store it in a separate file without the default .txt extension. This file can then be later included using the literalinclude directive.

Writing Conventions

Do not use contractions (can't, isn't, I'll, etc.) or '&' in the documentation.
All H1 and H2 level headings should have a capital letter at the start of each word.
All sub-headings (H3 +) should begin with a capital letter for the first word and continue in lowercase, except where they refer to terms which are abbreviated in the text e.g. Virtual Machine.
Use the full product name, e.g. OMERO.insight instead of Insight.
Avoid using resp. in brackets to refer to alternative file names etc. Just use 'or'.
Use full words rather than symbols in headings if possible.
When giving instructions, address the user as 'you' and try to maintain a professional attitude - i.e. no random asides about making coffee or smilies!
Bullet point lists should begin with a capital letter and end with a full stop if each point is a complete sentence, or more than one sentence. If not, no punctuation is necessary (see https://en.oxforddictionaries.com/punctuation/bullet-points).
Note that if you are giving an example link which is phrased like a hyperlink but not formatted as one because it does not actually exist, you need to prepend it with a '\' to escape the link and stop the link-checker from reporting it as broken (e.g. \http://your_host/webclient/login/), unless you use the literal mark-up.

Author: ome
Source Code: https://github.com/ome/omero-documentation

#python #sphinx

What is GEEK

Buddha Community

Sphinx Based Documentation for The Open Microscopy Environment

Jennie Hane

1653018360

Sphinx Based Documentation for The Open Microscopy Environment

Getting Started With Sphinx

Initial setup

Sphinx

The Sphinx documentation system can be obtained by issuing:

pip install Sphinx

Most Linux distributions will also provide it in a python-sphinx package (or similar).

Ant

You will also need ant for building the documentation. This can be installed on Mac OSX by using homebrew:

brew install ant

Structure and organization

The OME documentation is organized into multiple folders:

the OMERO documentation is under the omero folder,
the OME Contributing Developer documentation has been migrated to

ome-contributing, * the shared configuration and themes are under the common folder.

The structure of each documentation folder follows the Sphinx system guidelines. A quick overview:

source *.rst files with reST markup live in the root of the folder and under subfolders,
images/screenshots are placed under images,
downloadable files are placed under downloads,
compiled output is placed in _build,
compiled visual themes are automatically placed in _static,
Sphinx configuration is held in conf.py,
goals for make and make.bat are held in Makefile.

A reference of reStructuredText (reST) is available at https://thomas-cokelaer.info. It is recommended to familiarise oneself with the syntax outlined there.

A tutorial covering Sphinx, which enhances working with reST documents, can be found at http://sphinx.pocoo.org.

Building the documentation

The documentation may be built with make or ant. Note that ant requires ant-contrib to be on the classpath.

Basic build commands

To build a set of documentation, first move to the documentation folder. To build the OMERO documentation:

cd omero/

To clean the build directory of any previous builds, use one of:

make clean
ant clean

To build the documentation locally in the form of HTML pages, use one of:

make html
ant html

To check the links (internal and external) of the documentation, use one of:

make linkcheck
ant linkcheck

By default, make will build the documentation locally in the form of HTML pages.

Top-level build command

The top-level directory Makefile also defines targets for building both the OMERO and Contributing sets of documentation at once.

To clean the build directories of any previous builds, use one of:

make clean
ant clean

To build the sets of documentation locally in the form of HTML pages, use one of:

make html
ant html

By default, running make will build the documentation locally in the form of HTML pages.

Makefile options

Additional options for sphinx-build can be passed using the SPHINXOPTS variable. The -W option turns all warnings into errors:

SPHINXOPTS=-W make clean html
SPHINXOPTS=-W ant clean html

Release number

The release number of the OMERO documentation is UNKNOWN by default. To modify this value set the environment variable OMERO_RELEASE e.g.:

cd omero && OMERO_RELEASE=5.4.0 make clean html
cd omero && OMERO_RELEASE=5.4.0 ant clean html

This variable needs to be set to build all the version-dependent content used in the system administrator documentation correctly.

The Contributing Developer documentation has the release version removed as the intention is to update these files as and when necessary, so that they always reflect our current practices.

Zip bundles

To build the documentation as a zipped bundle, use:

ant zip

By default, running ant will build as a zipped bundle.

From the top level directory:

OMERO_RELEASE=5.4.0 ant zip -Domero.release="5.4.0"

will generate the HTML documentation for OMERO and Contributing and bundle just the OMERO documentation into an OMERO.doc-5.4.0.zip under omero/_build.

From omero directory:

OMERO_RELEASE=5.4.0 ant zip -Domero.release="5.4.0"

will generate the HTML documentation for OMERO and create an OMERO.doc-5.4.0.zip under omero/_build.

Auto-generated content

WORSKSPACE=/path/to/OMERO/deliverables ./omero/autogen_docs

Conventions Used

Part of the conventions used here is based on work by Benoît Bryon.

File names

reST source file names should carry the rst suffix and use lowercase alphanumeric characters and the - (minus) symbol.

Indentation

Example:

.. toctree::
    :maxdepth: 2

    Some content here...

Line wrapping

reST source files should use 78 lines for wrapping text. Please consult the manual of your favourite text editor to see how to switch on text wrapping.

Blank lines

Two new lines should be put before top-lined, top-level section names, i.e. before H1 and H2. One new line in any other case.

Example:

###############
Part title (H1)
###############

Introduction text.
(blank)
(blank)
******************
Chapter title (H2)
******************

Title headings

Every reST source file should begin with an H2 (level two) title. H1 titles are reserved for the index files (index.rst).

The following symbols should be used to create headings:

# with top line for parts
* with top line for chapters
= for sections
- for subsections
^ for subsubsections
" for paragraphs

Example:

###############
Part Title (H1)
###############

H1 only in indexes.


******************
Chapter Title (H2)
******************

Sample file content.


********************
Another chapter (H2)
********************

Section title (H3)
==================

Subsection title (H4)
---------------------

Subsubsection title (H5)
^^^^^^^^^^^^^^^^^^^^^^^^

Paragraph title (H6)
""""""""""""""""""""

And some text.

Page labels and references

Only when a good reason exists, a document can also start with a label:

.. _page-label:


Title Of The Page
=================

Images vs. figures

reST allows for two types of image embedding: using the image and figure directive. It is recommended to use the latter, as legends and captions can be added easier.

All images referenced in a reST document shall be placed in an images folder in the top-level directory of the documentation.

Please do not use relative (../../../images/foo.jpg) paths to refer to images. Sphinx does a good job at creating paths, so one can use /images/foo.jpg

Tables

.. csv-table::
    :widths: 20 80
    :header-rows: 1
    :file: searchfieldnames.tsv
    :delim: tab

Substitutions, aliases and hyperlinks

reST allows for using substitutions in cases where a piece of markup is used more than once, e.g.:

Please visit Python.org_

...

.. _Python.org: https://www.python.org

If a hyperlink appears only once, please use anonymous, "one-off" hyperlinks (two underscores):

`RFC 2396 <https://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC
2732 <https://www.rfc-editor.org/rfc/rfc2732.txt>`__ together
define the syntax of URIs.

Finally, please avoid using here as the hyperlink name, as in:

(...) go `here <http://www.google.com>`_.

Common markups

Please try to follow the rules outlined in Inline Markup. This allows for improving the semantics of the document elements.

Notes should be formatted using the note directive: .. note::
Definition lists can be created and cross-referenced using the glossary directive: .. glossary::. Each definition can be referenced anywhere in the documentation using the :term: role and an entry will be added for every term in the generated index.
References to external documentation can be formatted using: .. seealso::
Menu selections should be marked using the appropriate role: :menuselection: `Start --> Programs`
Environment variables should be formatted using the :envvar: role. This role will add an entry for the variable in the generated index.
CLI Commands can be formatted using the following role: :omerocmd: `admin start` This role will render as omero admin start and add an entry for the command in the generated index.
Other commands should be formatted using the literal markup: :literal: `command` or double back quoted markup
Configuration properties for OMERO.server and OMERO.web are marked using the custom property directive and can be cross referenced e.g. using :property: `omero.data.dir`
Other useful inline markups include: :option: and :guilabel:
Do not use inline highlighting or other markups in headings or subheadings

Global substitutions

Some substitutions have been implemented using rst_epilog in conf.py. They can be used in all pages of the documentation.

Hyperlinks

The table below lists targets for common hyperlinks.

Target name	Link
Python	https://www.python.org
Matplotlib	https://matplotlib.org/
Pillow	https://pillow.readthedocs.org
Hibernate	http://www.hibernate.org
ZeroC	https://zeroc.com
Ice	https://zeroc.com
Jenkins	https://jenkins.io/
roadmap	https://trac.openmicroscopy.org/ome/roadmap
Open Microscopy Environment	https://www.openmicroscopy.org
Glencoe Software, Inc.	https://www.glencoesoftware.com/
PyPI	https://pypi.org

Abbreviations

The table below lists substitutions for common abbreviations. These substitutions use the :abbr: Sphinx role meaning they are shown as tool-tip in HTML.

Name	Abbreviation	Explanation
\|SSH\|	SSH	Secure Shell
\|VM\|	VM	Virtual Machine
\|OS\|	OS	Operating System
\|SSL\|	SSL	Secure Socket Layer
\|HDD\|	HDD	Hard Disk Drive
\|CLI\|	CLI	Command Line Interface

OMERO page references

The table below lists substitutions that can be used to create references to sections of the OMERO documentation.

Name	Path
\|OmeroPy\|	developers/Python
\|OmeroCpp\|	developers/Cpp
\|OmeroJava\|	developers/Java
\|OmeroMatlab\|	developers/Matlab
\|OmeroApi\|	developers/Modules/Api
\|OmeroWeb\|	developers/Web
\|OmeroClients\|	developers/GettingStarted
\|OmeroGrid\|	sysadmins/grid
\|OmeroSessions\|	developers/Server/Sessions
\|OmeroModel\|	developers/Model
\|ExtendingOmero\|	developers/ExtendingOmero
\|BlitzGateway\|	developers/Python

For the most up-to-date list, please consult conf.py (section rst_epilog).

Common URLs

Some URLs are widely used across the OME documentation. Using the Sphinx extlinks extension, a dictionary of aliases to base URLs has been defined for the following:

image.sc forum: :imagesc: `tag <tag>`
Trac tickets: :ticket: `3442`, displayed as <a>#3442</a>
Snapshots: :snapshot: `omero/myzip.zip`
Website pages: :omero: `OMERO <>`
Downloads: :downloads: `OMERO downloads <>`

For the most up-to-date list, please consult conf.py (section extlinks). Note that there are separate conf.py files for each set of documentation, as well as a shared one under common/.

Source code links

SOURCE_USER=sbesson SOURCE_BRANCH=my_branch make clean html
SOURCE_USER=sbesson SOURCE_BRANCH=my_branch ant clean html

Jenkins links

Mailing-list links

For the legacy OME mailing lists, to point at specific discussion threads, two aliases have been defined, ome-users and ome-devel, e.g. :ome-users:`ome-users thread <2009-June/001839.html>`.

Inclusion of content

Writing Conventions

Do not use contractions (can't, isn't, I'll, etc.) or '&' in the documentation.
All H1 and H2 level headings should have a capital letter at the start of each word.
All sub-headings (H3 +) should begin with a capital letter for the first word and continue in lowercase, except where they refer to terms which are abbreviated in the text e.g. Virtual Machine.
Use the full product name, e.g. OMERO.insight instead of Insight.
Avoid using resp. in brackets to refer to alternative file names etc. Just use 'or'.
Use full words rather than symbols in headings if possible.
When giving instructions, address the user as 'you' and try to maintain a professional attitude - i.e. no random asides about making coffee or smilies!
Bullet point lists should begin with a capital letter and end with a full stop if each point is a complete sentence, or more than one sentence. If not, no punctuation is necessary (see https://en.oxforddictionaries.com/punctuation/bullet-points).
Note that if you are giving an example link which is phrased like a hyperlink but not formatted as one because it does not actually exist, you need to prepend it with a '\' to escape the link and stop the link-checker from reporting it as broken (e.g. \http://your_host/webclient/login/), unless you use the literal mark-up.

Author: ome
Source Code: https://github.com/ome/omero-documentation

#python #sphinx

Nat Grady

1646305020

Sphinx: Main Repository for The Sphinx Documentation Builder

Sphinx

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of multiple reStructuredText sources), written by Georg Brandl. It was originally created for the new Python documentation, and has excellent facilities for Python project documentation, but C/C++ is supported as well, and more languages are planned.

Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.

Among its features are the following:

Output formats: HTML (including derivative formats such as HTML Help, Epub and Qt Help), plain text, manual pages and LaTeX or direct PDF output using rst2pdf
Extensive cross-references: semantic markup and automatic links for functions, classes, glossary terms and similar pieces of information
Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
Automatic indices: general index as well as a module index
Code handling: automatic highlighting using the Pygments highlighter
Flexible HTML output using the Jinja 2 templating engine
Various extensions are available, e.g. for automatic testing of snippets and inclusion of appropriately formatted docstrings
Setuptools integration

For more information, refer to the the documentation.

Installation

Sphinx is published on PyPI and can be installed from there:

pip install -U sphinx

We also publish beta releases:

pip install -U --pre sphinx

If you wish to install Sphinx for development purposes, refer to the contributors guide.

Documentation

Documentation is available from sphinx-doc.org.

Get in touch

Report bugs, suggest features or view the source code on GitHub.
For less well defined questions or ideas, use the mailing list.

Please adhere to our code of conduct.

Testing

Continuous testing is provided by Travis (for unit tests and style checks on Linux), AppVeyor (for unit tests on Windows), and CircleCI (for large processes like TeX compilation).

For information on running tests locally, refer to the contributors guide.

Contributing

Refer to the contributors guide.

Release signatures

Releases are signed with following keys:

Author: Sphinx-doc
Source Code: https://github.com/sphinx-doc/sphinx
License: View license

#python #document #sphinx

Gloria magee

1618472877

Cannot start Microsoft Office Outlook

On this site, you’ll see working methods to repair the “can’t start Microsoft Outlook” issue. Additionally, these methods can enable you to get up your Outlook and running again without any mistakes.

Now, let us see how it is possible to fix and prevent a much worse situation when you can’t start Outlook. But first, we’re beginning from the reason and symptoms of the mistake.

Recover your Outlook with Outlook PST Recovery.

Which are the causes and symptom of the “Don’t start Microsoft Outlook” mistake?

The most important symptom of the matter is quite clear and readily identifiable. After you click on Outlook you’ll discover a dialogue box appears and can be hanging for a little while, then you receive the “can’t start Microsoft view. cannot open the outlook window. The set of connections can’t be opened” error.

Can’t start Microsoft Outlook

In case the file has corrupted then you are going to discover that its dimensions become kb.

Additionally, there’s absolutely no specific cause for this mistake, but all versions of MS Outlook from 2003 into Outlook 2019 might be impacted. Anyhow, whatever the motive is, the result is the same – you can’t start Outlook. . And the answers for this query are given below.

Workarounds to Solve “Don’t start Microsoft Outlook” problem

Now you understand the reasons why causes “can’t start Microsoft outlook. Cannot open the view window. The collection of folders cannot be opened” problem. Therefore, let us see how to have them repaired. Below there are 2 workarounds that fix this situation.

1. Recover the Navigation Pane configuration file

Typically it’s the corrupt Navigation Pane settings file that limits Microsoft Outlook from the beginning, so the first thing you have to do would be to regain it. Here is how you can do this task:

Click on the Start button.

Following that, Compose the"outlook.exe /resetnavpane" control and click on OK.

If you discover any difficulty and unable to recoup the Navigation pane settings document, then attempt to manually delete the XML file which stores the navigation pane configurations. To do this, go using the next measures:

It’ll open the folder in which MS Outlook Setup files are saved.

Cannot start Microsoft Outlook

2. Repair your Outlook data files with the help of Scanpst.exe.

Then default Outlook data file PST may be damaged or deleted, that’s the reason you can’t start Outlook. The document Outlook.pst isn’t a personal folders file"

To do so, do the Actions listed below:

Below you’ll discover Scanpst.exe from the listing. Double click it.

Additionally, you can go via Start and kind scanpst.exe from the Search box.

Following that, you’ll discover a window click the Browse button to choose your default Outlook.pst file.

After a couple of minutes, your document is going to be fixed.

Hopefully, your document got fixed. If not Then You Need to attempt the alternative provided below:

The majority of the time it fixes the documents. However, if the corruption is intense then this instrument fails. In these situations, you want to utilize PST File Retrieval designed by Mailconvertertools. A novice user can utilize this tool and fix their own Outlook PST files. It’s the very best way to recuperate and fix Outlook PST files and it simplifies all the constraints of the Inbox Repair Tool.

Conclusion

This technical manual is all about how to resolve “can’t start Microsoft outlook. Cannot open the view window. The collection of folders cannot be opened” I am hoping that your issue has been solved. When there’s any difficulty regarding any measure then don’t hesitate to contact.

#cannot open the outlook window #the set of folders cannot be opened outlook #outlook the set of folders cannot be opened #the set of folders cannot be opened outlook 2016 #outlook the information store cannot be opened #outlook information store could not be opened

Mathew Ssebatta

1640278800

How to Automate Excel Via PowerShell without installing Excel

PowerShell + Excel = Better Together

Automate Excel via PowerShell without having Excel installed. Runs on Windows, Linux and MAC. Creating Tables, Pivot Tables, Charts and much more has just become a lot easier.

Open ImportExcel as a remote repo in VS Code, without cloning it.

Open in Visual Studio Code

CI System	Environment	Status
Azure DevOps	Windows
Azure DevOps	Windows (Core)
Azure DevOps	Ubuntu
Azure DevOps	macOS

Install from the PowerShell Gallery.

Install-Module -Name ImportExcel

Donation

If this project helped you reduce the time to get your job done, let me know, send a coffee.

How to Videos

PowerShell Excel Module - ImportExcel

Installation -

PowerShell V5 and Later

You can install the ImportExcel module directly from the PowerShell Gallery

[Recommended] Install to your personal PowerShell Modules folder

Install-Module ImportExcel -scope CurrentUser

[Requires Elevation] Install for Everyone (computer PowerShell Modules folder)

Install-Module ImportExcel

Continuous Integration Updates

Big thanks to Illy for taking the Azure DevOps CI to the next level. Improved badges, improved matrix for cross platform OS testing and more.

Plus, wiring the PowerShell ScriptAnalyzer Excel report we built into each run as an artifact.

What's new 7.1.3

Changed to ProviderPath. Thanks Trevor Walker

What's new 7.1.2

Get-ExcelFileSummary - Gets summary information on an Excel file like number of rows, columns, and more

dir . -r *.xlsx | Get-ExcelFileSummary | ft

ExcelFile          WorksheetName Rows Columns Address Path
---------          ------------- ---- ------- ------- ----
Grades.xlsx        Sheet1          21       3 A1:C21  D:\temp\ExcelYouTube\Grades
GradesAverage.xlsx Sheet1          21       5 A1:E21  D:\temp\ExcelYouTube\Grades
AllShifts.xlsx     Sheet1          21       2 A1:B21  D:\temp\ExcelYouTube\SeparateData
Shift_1.xlsx       Sheet1          10       2 A1:B10  D:\temp\ExcelYouTube\SeparateData
Shift_2.xlsx       Sheet1           8       2 A1:B8   D:\temp\ExcelYouTube\SeparateData
Shift_3.xlsx       Sheet1           5       2 A1:B5   D:\temp\ExcelYouTube\SeparateData
Shifts.xlsx        Shift_1         10       2 A1:B10  D:\temp\ExcelYouTube\SeparateData
Shifts.xlsx        Shift_2          8       2 A1:B8   D:\temp\ExcelYouTube\SeparateData

What's new 7.1.1

Merged Nate Ferrell's Linux fix. Thanks!
Moved Export-MultipleExcelSheets from psm1 to Examples/Experimental
Deleted the CI build in Appveyor
Thank you Mikey Bronowski for
- Multiple sweeps
- Standardising casing of parameter names, and variables
- Plus updating > 50 of the examples and making them consistent.

What's new 7.1.0

Fixes, Updates and new Examples

Fixed

Odd behavior on the return of Import-Excel function https://github.com/dfinke/ImportExcel/issues/792
Export-Excel -FreezeTopRow with -Title https://github.com/dfinke/ImportExcel/issues/795
Not importing when first row contains a 0 in a column https://github.com/dfinke/ImportExcel/issues/802

Updated

Add -AsDate support to Import-Excel and ConvertFrom-ExcelSheet

New Examples

PS1	Description	Link
Pester-To-XLSx	Runs Pester, collects the results, enriches it, and exports it to Excel	Pester-To-XLSx.ps1
DSUM	Sums up the numbers in a field (column) of records in a list or database that match conditions that you specify.	DSUM.ps1
VLookup	Setups up a sheet, you enter the name of an item and the amount is looked up	VLOOKUP.ps1

What's new 7.0.1

More infrastructure improvements.

Refine pipeline script analysis
Improve artifacts published
Add manifest (psd1) checks

What's new 7.0.0

Refactor

Remove all functions from the psm1
Move functions into public subdirectory
Align TDD and continuous integration workflow for this refactor
Move help from functions to mdHelp and use PlatyPS to generate external help file

Thanks to James O'Neill for the refactor and Illy on the continuous integration.

What's new 6.5.3

Thanks again to the community for making this module even better.

Fix import excel headers
Numerous improvements for DataTables and exporting it to Excel James O'Neill
- Names, styles, proper appending
Handles marking the empty row on an empty table as dummy row
Re-work code based on linting recommendations
Update existing tests and add more
Support PipelineVariable thanks to Luc Dekens for reporting and Ili for the PR
Fix quoting in ConvertFromExcelToSQLInsert beckerben

What's new 6.5.2

Thank you uSlackrill

Fixes Column order issue (plus tests) for Get-ExcelColumnName

Thank you jhoneill

Added -Force to Send-SQLDataToExcel so it sends something even if no rows are returned. (see #703)
Added -asText to import-Excel see (#164)[https://github.com/dfinke/ImportExcel/issues/164] and multiple others
Linux. Now set an environment variable if the support needed for Autosize is present, and use that Environment variable to decide to skip autosize operations.
Fixed tests which needed autosize to work so they skip of the environment variable is set.
Fixed another break where on azure the module never loaded.
Add a comment to ci.ps1 re better .NET version detection and left some commented out code.

Other

Added the example ReadAllSheets.ps1 based on this thread https://github.com/dfinke/ImportExcel/issues/678

What's new 6.5.0

This is now using the latest version of EPPlus. Unit tests are updated and passing, if you hit problems, please open an issue. You can rollback to an older version from the PowerShell Gallery if you are blocked.

Unit tests were updated and fixed
"Set-WorksheetProtection" is now switched on
Made a change to make Set-Excel range more friendly when Auto Sizing on non-windows platforms
Fixed - Windows only tests don't attempt to run on non-windows systems
Tests based on Get-Process don't attempt to run if <20 processes are returned
If $env:TEMP is not set (as will be the case on Linux)
Join-Path if used so paths are built with / or with as suits the OS where the test is running.
Excel Sparklines now supported, check out the examples SalesByQuarter and Sparklines.

What's new 6.2.4

Sensible parameter defaults, make your life easier and gets things done faster.

Thank you to DomRRuggeri for the initial Out-Excel PR and kicking off the conversation on the improvements.
Thank you to ili101 for refactoring and improving the defaults, and adding the tests for parameters.
Creates a table, with filtering
Chooses a TableStyle
Displays the Excel spreadsheet automatically

Get-Process | select Company, Name, Handles | Export-Excel

What's new 6.2.3

Thank you jhoneill.

Refactored copy sheet and added pipe support
Add ClearAll to Set-ExcelRange
Fix broken test & regression for passwords
- Note: Passwords do not work on pwsh. The EPPlus library does not support these dotnet core APIs at this time.

What's new 6.2.2

Added requested feature, chart trendlines.
- Example PowerShell script

Fixed Import-Excel and relative path issue, added unit tests.

What's new 6.2.0

Thank you to James O'Neill

Fixed, Import-Excel can read xlsx files even if already open in Excel
Added New-ExcelStyle, plus -Style to Export-Excel and -Merge to Set-ExcelRange
Added Style Examples

What's new 6.1.0

Thank you to James O'Neill

Instead of specifying a path provides an Excel Package object (from Open-ExcelPackage), using this avoids re-reading the whole file when importing multiple parts of it. To allow multiple read operations Import-Excel does NOT close the package, and you should use Close-ExcelPackage -noSave to close it.

What's new 6.0.0

Thank you to James O'Neill for the optimizations, and refactoring leading to a ~10x speed increase. Thanks to ili101 for earlier PRs that provided the ground work for this.

Performance improvement to Export-Excel see #506 and #555. This has meant taking code in Add-CellValue back into process block of Export-Excel, as the overhead of calling the function was a lot greater than time executing the code inside it. Blog post to follow. Some tests are showing a ~10x speed increase. #572 was about a broken #region tag in this part of the code and that has been cleaned up in the process.
Export-Excel now has an -InputObject parameter (this was previously -TargetData , which is now an alias for InputObject). If the inputobject is an array, each item will be inserted, so you can run export-excel -inputobject $x rather than $x | Export-Excel, and if it is a system.data.datatable object it will be inserted directly rather than cell-by-cell. Send-SQLDataToExcel takes advantage of this new functionality. There are simple tests for these new items
Export-Excel previously assumed -Now if there were no other parameters, it will now assume -Now if there is no -Path or -ExcelPackage. The .PSD1 file now itemizes the items exported by the module #557

What's new 5.4.5

Thank you to James O'Neill for the great additions.

Modified Send-SQLDataToExcel so it creates tables and ranges itself; previously it relied on export-excel to do this which cause problems when adding data to an existing sheet (#555)
Added new command Add-ExcelDataValidation which will apply different data-validation rules to ranges of cells
Changed the export behavior so that (1) attempts to convert to a number only apply if the the value was a string; (2) Nulls are no longer converted to an empty string (3) there is a specific check for URIs and not just text which is a valid URI. Using UNC names in hyperlinks remains problematic.
Changed the behavior of AutoSize in export excel so it only applies to the exported columns. Previously if something was exported next to pre-existing data, AutoSize would resize the whole sheet, potentially undoing things which had been set on the earlier data. If anyone relied on this behavior they will need to explicitly tell the sheet to auto size with $sheet.cells.autofitColumns. (where $sheet points to the sheet, it might be $ExcelPackage.Workbook.Worksheets['Name'])
In Compare-Worksheet,the Key for comparing the sheets can now be written as a hash table with an expression - it is used with a Group-Object command so if it is valid in Group-Object it should be accepted; this allows the creation of composite keys when data being compared doesn't have a column which uniquely identifies rows.
In Set-ExcelRange , added a 'Locked' option equivalent to the checkbox on the Protection Tab of the format cells dialog box in Excel.
Created a Set-WorksheetProtection function. This gives the same options the protection dialog in Excel but is 0.9 release at the moment.

New Example

Added MutipleValidations.ps1. Culled from the tests.

What's new 5.4.4

Fix issue when only a single property is piped into Export-Excel
Fix issue in Copy-ExcelWorksheet, close the $Stream

What's new 5.4.3

Added Remove-Worksheet: Removes one or more worksheets from one or more workbooks

What's new 5.4.2

Added parameters -GroupDateRow and -GroupDatePart & -GroupNumericRow, -GroupNumericMin, -GroupNumericMax and -GroupNumericInterval

to Add-PivotTable and New-PivotTableDefinition. The date ones gather dates of the same year and/or quarter and/or month and/or day etc.

the number ones group numbers into bands, starting at Min, and going up steps specified by Interval. Added tests and help for these.

Set-ExcelRow and Set-ExcelColumn now check that the worksheet name they passed exists in the workbook.

What's new 5.4.0

Thank you to Conrad Agramont, Twitter: @AGramont for the AddMultiWorkSheet.ps1 example. Much appreciated!
Fixed several more bugs where parameters were ignored if passed a zero value
Fixed bug where chart series headers could not come form a cell reference (=Sheet1!Z10 now works as a header reference)
Add-Chart will now allow a single X range, or as many X ranges as there are Y ranges.
Merge-MultipleSheets is more robust.
Set-ExcelRow and Set-ExcelColumn trap attempts to process a sheet with no rows/columns.
Help has been proof-read (thanks to Mrs. @Jhoneill !).

What's new 5.3.4

HotFix for parameter PivotTableStyle should be PivotTableStyle https://github.com/dfinke/ImportExcel/issues/453

What's new 5.3.3

Thank you to (lazywinadmin)[https://github.com/lazywinadmin] - Expand aliases in examples and elsewhere
In Export-Excel fixed a bug where -AutoNameRange on pre-existing data included the header in the range.
In Export-Excel fixed a bug which caused a zero, null, or empty string in a list of simple objects to be skipped.
In Export-Excel improved the behaviour when a new worksheet is created without data, and Tables etc are added to it.
In Join-Worksheet: added argument completer to -TitleBackgroundColor and set default for -TitleBackgroundStyle to 'Solid'.
In Add-Excel chart, New-ExcelChart, tests and Examples fixed mis-spelling of "Position"
In Send-SqlDataToExcel: improved robustness of check for no data returned.
In Set-ExcelColumn: -column can come from the pipeline (supporting an array introduces complications for supporting script blocks); -AutoNameRange no longer requires heading to specified (so you can do 1..10 | Set-ExcelColumn -AutoNameRange ); In Set-ExcelRow: -Row can come from the pipeline
Improved test coverage (back over 80%).
Help and example improvements. In "Index - music.ps1" the module for querying the index can be downloaded from PowerShell gallery #requires set to demand it. In SQL+FillColumns+Pivot\example2.ps1 the GetSQL module can be downloaded and #Requires has been set. The F1 results spreadsheet is available from one drive and a link is provided.
Added Azure DevOps continuous integration and badges

What's new in Release 5.3

Help improvements and tidying up of examples and extra examples
Open-Excel Package and Add-Worksheet now add worksheets as script properties so $Excel = Open-ExcelPackage -path test.xlsx ; $excel.sheet1 will return the sheet named "sheet1" $Excel.SheetName is a script property which is defined as $this.workbook.worksheets["Sheetname"]
Renamed Set-Column to Set-ExcelColumn, Set-Row to Set-ExcelRow, and Set-Format, to Set-ExcelRange. Added aliases so the old names still work.
Set-ExcelRange (or set-Format) used "Address" and "Range" incorrectly. There is now a single parameter -Range, with an alias of "Address". If the worksheet parameter is present, the function accepts a string specifying cells ("A1:Z10") or a the name of range. Without the worksheet it accepts an object representing a named range or a Table; or a tables's address, or part of the worksheet.cells collection.
Add-ConditionalFormatting: Used "address" correctly, and it will accept ranges in the address parameter (range is now an alias for address). It now wraps conditional value strings in quotes when needed (for = <= >= operations string needs to be in double quotes see issue #424). Parameter intellisense has been improved. There are new parameters: -StopIfTrue and -Priority and support for using the -Reverse parameter with Color-scale rules (issue #430). Booleans in the sheet are now supported as the value for a condition. Also brought the two different kinds of condition together inside Export-Excel, and fixed a bug where named-ranges didn't work in some places. In New-ConditionalText, more types of conditional format are supported, and the argument completer for -ConditionalTextColor was missing and has been added.
Improved handling of hyperlinks in Export-Excel (see issue #426)s
Export-Excel has better checking of Table and PivotTable names (for uniqueness) and a new test in quick charts that there is suitable data for charting. It also accepts hash tables for chart, pivot table and conditional formatting parameters which are splatted into the functions which add these.
Moved logic for adding a named-range out of Export-Excel and into a new function named Add-ExcelName, and logic for adding a table into a function named Add-ExcelTable; this is to make it easier to do these things independently of Export-Excel, but minimize duplication. The Add-ExcelTable command has extra parameters to toggle the options from table tools toolbar (show totals etc.) and set options in the totals row.
Moved PivotTable Functions out of Export-Excel.PS1 into their own file and moved Add-ExcelChart out of Export-Excel.ps1 into New-ExcelChart.ps1
Fixed bug in Merge-MultipleSheets where background pattern was set to None, making background color invisible.
Fixed issues where formatting could be reset when using Export-Excel to manipulate an existing sheet without appending data; this applied to number-formats and tables.
Add-PivotTable has some new parameters -PassThru returns the pivot table (e.g. to allow names /sort orders of data series to be tweaked ) -Address allows Pivot to be placed on an existing sheet; -PivotTableStyle allows a change from "Medium6", -PivotNumberFormat formats data cells. It is more flexible about how the source data is specified - copying the range options in Set-ExcelRange. Add-ExcelChart is now used for creating PivotCharts, and -PivotChartDefinition allows a definition created with New-ExcelChartDefinition to be used when setting up a PivotTable. This opens up all the things that Add-ExcelChart can do without duplicating the parameters on Add-Pivot table and Export-Excel. Definition, TableStyle, Numberformat and ChartDefiniton can be used in New-PivotTableDefinition .
Add-ExcelChart now supports -PassThru to return the chart for tweaking after creation; there is now a -PivotTable parameter to allow Add-PivotTable to call the code in Add-ExcelChart. And in New-ExcelChartDefinition Legend parameters (for size, bold & position ) are now supported
ChartDefinition and conditional formatting parameters can now be hashtables - anything that splats Add-ExcelChart or Add-ConditionalFormatting, it should be acceptable as a definition.

What's new in Release 5.2

Value does not need to be mandatory in Set-Row or Set-Column, also tidied their parameters a little.
Added support for array formulas in Set-Format (it really should be set range now that it sets values, formulas and hyperlinks - that can go on the to-do list )
Fixed a bug with -Append in Export-Excel which caused it to overwrite the last row if the new data was a simple type.
NumberFormat in Export-Excel now sets the default for on a new / blank sheet; but [still] sets individual cells when adding to a sheet
Added support for timespans in Export excel ; set as elapsed hours, mins, secs [h]:mm:sss
In Export-Excel improved the catch-all handler for insuring values to cope better with nested objects (#419) and reduce the number of parse operations
Added -Calculate switch to Export-Excel and Close-Excel Package; EPPlus needs formulas to OMIT the leading = sign so where formula is set it now strips a leading = sign
Added -PivotTotals parameter where there was already -NoTotalsInPivot new one allows None, Both, Rows, Columns. (#415)
When appending Export-Excel only extended tables and ranges if they were explicitly specified. It now does it automatically.
Compare and Merge worksheet originally had a problem with > 26 columns, I fixed merge turns out I hadn't fixed compare ... I have now
Fixed bug where Export-Excel would not recognize it had to set $TitleFillPattern - made the default 'Solid'
ExcludeProperty in Export-Excel now supports wildcards.
Added DateTime to the list of types which can be exported as single column.
Added Password support to Open- and Close-ExcelPackage (password was not doing anything in Export-Excel)
Gave Expand-NumberFormat a better grasp of currency layouts - it follows .NET which is not always the same as Excel would set:-(

What's new in Release 5.1.1

Set-Row and Set-Column will now create hyperlinks and insert dates correctly
Import-Excel now has an argument completer for Worksheet name - this can be slow on large files
The NumberFormat parameter (in Export-Excel, Set-Row, Set-Column, Set-Format and Add-ConditionalFormat) and X&YAxisNumberFormat parameters (in New-ExcelChartDefinition and Add-ExcelChart) now have an argument completer and the names Currency, Number, Percentage, Scientific, Fraction, Short Date ,Short time,Long time, Date-Time and Text will be converted to the correct Excel formatting strings.
Added new function Select-Worksheet to make a named sheet active: Added -Activate switch to Add-Worksheet, to make current sheet active, Export-Excel and Add-PivotTable support -Activate and pass it to Add-Worksheet, and New-PivotTableDefinition allows it to be part of the Pivot TableDefinition.
Fixed a bug in Set-Format which caused -Hidden not to work
Made the same changes to Add-Conditional format as set format so -switch:$false is processed, and 0 enums and values are processed correctly
In Export-Excel, wrapped calls to Add-CellValue in a try catch so a value which causes an issue doesn't crash the whole export but generates a warning instead (#410) .
Additional tests.

What's new to July 18

Changed parameter evaluation in Set-Format to support -bold:$false (and other switches so that if false is specified the attribute will be removed ), and to bug were enums with a value of zero, and other zero parameters were not set.
Moved chart creation into its own function (Add-Excel chart) within Export-Excel.ps1. Renamed New-Excelchart to New-ExcelChartDefinition to make it clearer that it is not making anything in the workbook (but for compatibility put an alias of New-ExcelChart in so existing code does not break). Found that -Header does nothing, so it isn't Add-Excel chart and there is a message that does nothing in New-ExcelChartDefinition .
Added -BarChart -ColumnChart -LineChart -PieChart parameters to Export-Excel for quick charts without giving a full chart definition.
Added parameters for managing chart Axes and legend
Added some chart tests to Export-Excel.tests.ps1. (but tests & examples for quick charts , axes or legends still on the to do list )
Fixed some bad code which had been checked-in in-error and caused adding charts to break. (This was not seen outside GitHub #377)
Added "Reverse" parameter to Add-ConditionalFormatting ; and added -PassThru to make it easier to modify details of conditional formatting rules after creation (#396)
Refactored ConditionalFormatting code in Export excel to use Add-ConditionalFormatting.
Rewrote Copy-ExcelWorksheet to use copy functionality rather than import | export (395)
Found sorts could be inconsistent in Merge-MultipleWorksheet, so now sort on more columns.
Fixed a bug introduced into Compare-Worksheet by the change described in the June changes below, this meant the font color was only being set in one sheet, when a row was changed. Also found that the PowerShell ISE and shell return Compare-Object results in different sequences which broke some tests. Applied a sort to ensure things are in a predictable order. (#375)
Removed (2) calls to Get-ExcelColumnName (Removed and then restored function itself)
Fixed an issue in Export-Excel where formulas were inserted as strings if "NoNumberConversion" is applied (#374), and made sure formatting is applied to formula cells
Fixed an issue with parameter sets in Export-Excel not being determined correctly in some cases (I think this had been resolved before and might have regressed)
Reverted the [double]::tryParse in export excel to the previous (longer) way, as the shorter way was not behaving correctly with with the number formats in certain regions. (also #374)
Changed Table, Range and AutoRangeNames to apply to whole data area if no data has been inserted OR to inserted data only if it has.(#376) This means that if there are multiple inserts only inserted data is touched, rather than going as far down and/or right as the furthest used cell. Added a test for this.
Added more of the Parameters from Export-Excel to Join-worksheet, join just calls export-excel with these parameters so there is no code behind them (#383)
Added more of the Parameters from Export-Excel to Send-SQLDataToExcel, send just calls export-excel with these parameters...
Added support for passing a System.Data.DataTable directly to Send-SQLDataToExcel
Fixed a bug in Merge-MultipleSheets where if the key was "name", columns like "displayName" would not be processed correctly, nor would names like "something_ROW". Added tests for Compare, Merge and Join Worksheet
Add-Worksheet , fixed a regression with move-after (#392), changed way default worksheet name is decided, so if none is specified, and an existing worksheet is copied (see June additions) and the name doesn't already exist, the original sheet name will be kept. (#393) If no name is given an a blank sheet is created, then it will be named sheetX where X is the number of the sheet (so if you have sheets FOO and BAR the new sheet will be Sheet3).

New in June 18

New commands - Diff , Merge and Join

Compare-Worksheet (introduced in 5.0) uses the built in Compare-object command, to output a command-line DIFF and/or color the worksheet to show differences. For example, if my sheets are Windows services the extra rows or rows where the startup status has changed get highlighted

Merge-Worksheet (also introduced in 5.0) joins two lumps, side by highlighting the differences. So now I can have server A's services and Server Bs Services on the same page. I figured out a way to do multiple sheets. So I can have Server A,B,C,D on one page :-) that is Merge-MultpleSheets

For this release I've fixed heaven only knows how many typos and proof reading errors in the help for these two, the only code change is to fix a bug if two worksheets have different names, are in different files and the Comparison sends the delta in the second back before the one in first, then highlighting changed properties could throw an error. Correcting the spelling of Merge-MultipleSheets is potentially a breaking change (and it is still plural!)

also fixed a bug in compare worksheet where color might not be applied correctly when the worksheets came from different files and had different name.

Join-Worksheet is new for this release. At it's simplest it copies all the data in Worksheet A to the end of Worksheet B

Add-Worksheet
- I have moved this from ImportExcel.psm1 to ExportExcel.ps1 and it now can move a new worksheet to the right place, and can copy an existing worksheet (from the same or a different workbook) to a new one, and I set the Set return-type to aid intellisense
New-PivotTableDefinition
- Now Supports -PivotFilter and -PivotDataToColumn, -ChartHeight/width -ChartRow/Column, -ChartRow/ColumnPixelOffset parameters
Set-Format
- Fixed a bug where the -address parameter had to be named, although the examples in export-excel help showed it working by position (which works now. )
Export-Excel
- I've done some re-factoring
  1. I "flattened out" small "called-once" functions , add-title, convert-toNumber and Stop-ExcelProcess.
  2. It now uses Add-Worksheet, Open-ExcelPackage and Add-ConditionalFormat instead of duplicating their functionality.
  3. I've moved the PivotTable functionality (which was doubled up) out to a new function "Add-PivotTable" which supports some extra parameters PivotFilter and PivotDataToColumn, ChartHeight/width ChartRow/Column, ChartRow/ColumnPixelOffsets.
  4. I've made the try{} catch{} blocks cover smaller blocks of code to give a better idea where a failure happened, some of these now Warn instead of throwing - I'd rather save the data with warnings than throw it away because we can't add a chart. Along with this I've added some extra write-verbose messages
- Bad column-names specified for Pivots now generate warnings instead of throwing.
- Fixed issues when pivot tables / charts already exist and an export tries to create them again.
- Fixed issue where AutoNamedRange, NamedRange, and TableName do not work when appending to a sheet which already contains the range(s) / table
- Fixed issue where AutoNamedRange may try to create ranges with an illegal name.
- Added check for illegal characters in RangeName or Table Name (replace them with "_"), changed tablename validation to allow spaces and applied same validation to RangeName
- Fixed a bug where BoldTopRow is always bolds row 1 even if the export is told to start at a lower row.
- Fixed a bug where titles throw pivot table creation out of alignment.
- Fixed a bug where Append can overwrite the last rows of data if the initial export had blank rows at the top of the sheet.
- Removed the need to specify a fill type when specifying a title background color
- Added MoveToStart, MoveToEnd, MoveBefore and MoveAfter Parameters - these go straight through to Add worksheet
- Added "NoScriptOrAliasProperties" "DisplayPropertySet" switches (names subject to change) - combined with ExcludeProperty these are a quick way to reduce the data exported (and speed things up)
- Added PivotTableName Switch (in line with 5.0.1 release)
- Add-CellValue now understands URI item properties. If a property is of type URI it is created as a hyperlink to speed up Add-CellValue
  - Commented out the write verbose statements even if verbose is silenced they cause a significant performance impact and if it's on they will cause a flood of messages.
  - Re-ordered the choices in the switch and added an option to say "If it is numeric already post it as is"
  - Added an option to only set the number format if doesn't match the default for the sheet.
Export-Excel Pester Tests
- I have converted examples 1-9, 11 and 13 from Export-Excel help into tests and have added some additional tests, and extra parameters to the example command to get better test coverage. The test so far has 184 "should" conditions grouped as 58 "IT" statements; but is still a work in progress.
Compare-Worksheet pester tests
James O'Neill added Compare-Worksheet
- Compares two worksheets with the same name in different files.

4/22/2018

Thanks to the community yet again

ili101 for fixes and features
- Removed [PSPlot] as OutputType. Fixes it throwing an error
Nasir Zubair added ConvertEmptyStringsToNull to the function ConvertFrom-ExcelToSQLInsert
- If specified, cells without any data are replaced with NULL, instead of an empty string. This is to address behaviors in certain DBMS where an empty string is insert as 0 for INT column, instead of a NULL value.

4/10/2018

-New parameter -ReZip. It ReZips the xlsx so it can be imported to PowerBI

Thanks to Justin Grote for finding and fixing the error that Excel files created do not import to PowerBI online. Plus, thank you to CrashM for confirming the fix.

Super helpful!

3/31/2018

Updated Set-Format
- Added parameters to set borders for cells, including top, bottom, left and right
- Added parameters to set value and formula

$data = @"
From,To,RDollars,RPercent,MDollars,MPercent,Revenue,Margin
Atlanta,New York,3602000,.0809,955000,.09,245,65
New York,Washington,4674000,.105,336000,.03,222,16
Chicago,New York,4674000,.0804,1536000,.14,550,43
New York,Philadelphia,12180000,.1427,-716000,-.07,321,-25
New York,San Francisco,3221000,.0629,1088000,.04,436,21
New York,Phoneix,2782000,.0723,467000,.10,674,33
"@

Added -PivotFilter parameter, allows you to set up a filter so you can drill down into a subset of the overall dataset.

$data =@"
Region,Area,Product,Units,Cost
North,A1,Apple,100,.5
South,A2,Pear,120,1.5
East,A3,Grape,140,2.5
West,A4,Banana,160,3.5
North,A1,Pear,120,1.5
North,A1,Grape,140,2.5
"@

3/14/2018

Thank you to James O'Neill, fixed bugs with ChangeDatabase parameter which would prevent it working

Added -Force to New-Alias

Add example to set the background color of a column

Supports excluding Row Grand Totals for PivotTables

Allow xlsm files to be read

Fix Set-Column.ps1, Set-Row.ps1, SetFormat.ps1, formatting.ps1 $false and $BorderRound

1/1/2018

Added switch [Switch]$NoTotalsInPivot. Allows hiding of the row totals in the pivot table.

Thanks you to jameseholt for the request.

    get-process | where Company | select Company, Handles, WorkingSet |
        export-excel C:\temp\testColumnGrand.xlsx `
            -Show -ClearSheet  -KillExcel `
            -IncludePivotTable -PivotRows Company -PivotData @{"Handles"="average"} -NoTotalsInPivot

Fixed when using certain a ChartType for the Pivot Table Chart, would throw an error
Fixed - when you specify a file, and the directory does not exit, it now creates it

11/23/2017

More great additions and thanks to James O'Neill

Added Convert-XlRangeToImage Gets the specified part of an Excel file and exports it as an image
Fixed a typo in the message at line 373.
Now catch an attempt to both clear the sheet and append to it.
Fixed some issues when appending to sheets where the header isn't in row 1 or the data doesn't start in column 1.
Added support for more settings when creating a pivot chart.
Corrected a typo PivotTableName was PivtoTableName in definition of New-PivotTableDefinition
Add-ConditionalFormat and Set-Format added to the parameters so each has the choice of working more like the other.
Added Set-Row and Set-Column - fill a formula down or across.
Added Send-SQLDataToExcel. Insert a rowset and then call Export-Excel for ranges, charts, pivots etc.

10/30/2017

Huge thanks to James O'Neill. PowerShell aficionado. He always brings a flare when working with PowerShell. This is no exception.

(Check out the examples help Export-Excel -Examples)

New parameter Package allows an ExcelPackage object returned by -passThru to be passed in
New parameter ExcludeProperty to remove unwanted properties without needing to go through select-object
New parameter Append code to read the existing headers and move the insertion point below the current data
New parameter ClearSheet which removes the worksheet and any past data
Remove any existing Pivot table before trying to [re]create it
Check for inserting a pivot table so if -InsertPivotChart is specified it implies -InsertPivotTable

(Check out the examples help Export-Excel -Examples)

New function Export-Charts (requires Excel to be installed) - Export Excel charts out as JPG files
New function Add-ConditionalFormatting Adds conditional formatting to worksheet
New function Set-Format Applies Number, font, alignment and color formatting to a range of Excel Cells
ColorCompletion an argument completer for Colors for params across functions

I also worked out the parameters so you can do this, which is the same as passing -Now. It creates an Excel file name for you, does an auto fit and sets up filters.

ps | select Company, Handles | Export-Excel

10/13/2017

Added New-PivotTableDefinition. You can create and wire up a PivotTable to a WorkSheet. You can also create as many PivotTable Worksheets to point a one Worksheet. Or, you create many Worksheets and many corresponding PivotTable Worksheets.

Here you can create a WorkSheet with the data from Get-Service. Then create four PivotTables, pointing to the data each pivoting on a different dimension and showing a different chart

$base = @{
    SourceWorkSheet   = 'gsv'
    PivotData         = @{'Status' = 'count'}
    IncludePivotChart = $true
}

$ptd = [ordered]@{}

$ptd += New-PivotTableDefinition @base servicetype -PivotRows servicetype -ChartType Area3D
$ptd += New-PivotTableDefinition @base status -PivotRows status -ChartType PieExploded3D
$ptd += New-PivotTableDefinition @base starttype -PivotRows starttype -ChartType BarClustered3D
$ptd += New-PivotTableDefinition @base canstop -PivotRows canstop -ChartType ConeColStacked

Get-Service | Export-Excel -path $file -WorkSheetname gsv -Show -PivotTableDefinition $ptd

10/4/2017

Thanks to https://github.com/ili101 :

Fix Bug, Unable to find type [PSPlot]
Fix Bug, AutoFilter with TableName create corrupted Excel file.

10/2/2017

Thanks to Jeremy Brun Fixed issues related to use of -Title parameter combined with column formatting parameters.

9/28/2017 (Version 4.0.1)

Added a new parameter called Password to import password protected files

Added even more Pester tests for a more robust and bug free module

Renamed parameter 'TopRow' to 'StartRow'

This allows us to be more concise when new parameters ('StartColumn', ..) will be added in the future Your code will not break after the update, because we added an alias for backward compatibility

Special thanks to robinmalik for providing us with the code to implement this new feature. A high five to DarkLite1 for the implementation.

9/12/2017 (Version 4.0.0)

Super thanks and hat tip to DarkLite1. There is now a new and improved Import-Excel, not only in functionality, but also improved readability, examples and more. Not only that, he's been running it in production in his company for a number of weeks!

Added Update-FirstObjectProperties Updates the first object to contain all the properties of the object with the most properties in the array. Check out the help.

Breaking Changes: Due to a big portion of the code that is rewritten some slightly different behavior can be expected from the Import-Excel function. This is especially true for importing empty Excel files with or without using the TopRow parameter. To make sure that your code is still valid, please check the examples in the help or the accompanying Pester test file.

Moving forward, we are planning to include automatic testing with the help of Pester, Appveyor and Travis. From now on any changes in the module will have to be accompanied by the corresponding Pester tests to avoid breakages of code and functionality. This is in preparation for new features coming down the road.

7/3/2017

Thanks to Mikkel Nordberg. He contributed a ConvertTo-ExcelXlsx. To use it, Excel needs to be installed. The function converts the older Excel file format ending in .xls to the new format ending in .xlsx.

6/15/2017

Huge thank you to DarkLite1! Refactoring of code, adding help, adding features, fixing bugs. Specifically this long outstanding one:

Export-Excel: Numeric values not correct

It is fantastic to work with people like DarkLite1 in the community, to help make the module so much better. A hat to you.

Another shout out to Damian Reeves! His questions turn into great features. He asked if it was possible to import an Excel worksheet and transform the data into SQL INSERT statements. We can now answer that question with a big YES!

ConvertFrom-ExcelToSQLInsert People .\testSQLGen.xlsx

INSERT INTO People ('First', 'Last', 'The Zip') Values('John', 'Doe', '12345');
INSERT INTO People ('First', 'Last', 'The Zip') Values('Jim', 'Doe', '12345');
INSERT INTO People ('First', 'Last', 'The Zip') Values('Tom', 'Doe', '12345');
INSERT INTO People ('First', 'Last', 'The Zip') Values('Harry', 'Doe', '12345');
INSERT INTO People ('First', 'Last', 'The Zip') Values('Jane', 'Doe', '12345');

Bonus Points

Use the underlying ConvertFrom-ExcelData function and you can use a scriptblock to format the data however you want.

ConvertFrom-ExcelData .\testSQLGen.xlsx {
    param($propertyNames, $record)

    $reportRecord = @()
    foreach ($pn in $propertyNames) {
        $reportRecord += "{0}: {1}" -f $pn, $record.$pn
    }
    $reportRecord +=""
    $reportRecord -join "`r`n"
}

Generates

First: John
Last: Doe
The Zip: 12345

First: Jim
Last: Doe
The Zip: 12345

First: Tom
Last: Doe
The Zip: 12345

First: Harry
Last: Doe
The Zip: 12345

First: Jane
Last: Doe
The Zip: 12345

2/2/2017

Thank you to DarkLite1 for more updates

TableName with parameter validation, throws an error when the TableName:
- Starts with something else then a letter
- Is NULL or empty
- Contains spaces
Numeric parsing now uses CurrentInfo to use the system settings

2/14/2017

Big thanks to DarkLite1 for some great updates

-DataOnly switch added to Import-Excel. When used it will only generate objects for rows that contain text values, not for empty rows or columns.

Get-ExcelWorkBookInfo - retrieves information of an Excel workbook.

      Get-ExcelWorkbookInfo .\Test.xlsx

      CorePropertiesXml     : #document
      Title                 :
      Subject               :
      Author                : Konica Minolta User
      Comments              :
      Keywords              :
      LastModifiedBy        : Bond, James (London) GBR
      LastPrinted           : 2017-01-21T12:36:11Z
      Created               : 17/01/2017 13:51:32
      Category              :
      Status                :
      ExtendedPropertiesXml : #document
      Application           : Microsoft Excel
      HyperlinkBase         :
      AppVersion            : 14.0300
      Company               : Secret Service
      Manager               :
      Modified              : 10/02/2017 12:45:37
      CustomPropertiesXml   : #document

12/22/2016

Added -Now switch. This short cuts the process, automatically creating a temp file and enables the -Show, -AutoFilter, -AutoSize switches.

Get-Process | Select Company, Handles | Export-Excel -Now

Added ScriptBlocks for coloring cells. Check out Examples

Get-Process |
    Select-Object Company,Handles,PM, NPM|
    Export-Excel $xlfile -Show  -AutoSize -CellStyleSB {
        param(
            $workSheet,
            $totalRows,
            $lastColumn
        )

        Set-CellStyle $workSheet 1 $LastColumn Solid Cyan

        foreach($row in (2..$totalRows | Where-Object {$_ % 2 -eq 0})) {
            Set-CellStyle $workSheet $row $LastColumn Solid Gray
        }

        foreach($row in (2..$totalRows | Where-Object {$_ % 2 -eq 1})) {
            Set-CellStyle $workSheet $row $LastColumn Solid LightGray
        }
    }

9/28/2016

Fixed PowerShell 3.0 compatibility. Thanks to headsphere. He used $obj.PSObject.Methods[$target] syntax to make it backward compatible. PS v4.0 and later allow $obj.$target.

Thank you to xelsirko for fixing - Import-module importexcel gives version warning if started inside background job

8/12/2016

Fixed reading the headers from cells, moved from using Text property to Value property.

7/30/2016

Added Copy-ExcelWorksheet. Let's you copy a work sheet from one Excel workbook to another.

7/21/2016

Fixes Import-Excel #68

7/7/2016

Attila Mihalicz fixed two issues

Removing extra spaces after the backtick
Uninitialized variable $idx leaks into the pipeline when -TableName parameter is used

Thanks Attila.

7/1/2016

Pushed 2.2.7 fixed resolve path in Get-ExcelSheetInfo
Fixed Casting Error in Export-Excel
For Import-Excel change Resolve-Path to return ProviderPath for use with UNC

6/01/2016

Added -UseDefaultCredentials to both Import-Html and Get-HtmlTable
New functions, Import-UPS and Import-USPS. Pass in a valid tracking # and it scrapes the page for the delivery details

4/30/2016

Huge thank you to Willie Möller

He added a version check so the PowerShell Classes don't cause issues for down-level version of PowerShell
He also contributed the first Pester tests for the module. Super! Check them out, they'll be the way tests will be implemented going forward

4/18/2016

Thanks to Paul Williams for this feature. Now data can be transposed to columns for better charting.

$file = "C:\Temp\ps.xlsx"
rm $file -ErrorAction Ignore

ps |
    where company |
    select Company,PagedMemorySize,PeakPagedMemorySize |
    Export-Excel $file -Show -AutoSize `
        -IncludePivotTable `
        -IncludePivotChart `
        -ChartType ColumnClustered `
        -PivotRows Company `
        -PivotData @{PagedMemorySize='sum';PeakPagedMemorySize='sum'}

Add -PivotDataToColumn

$file = "C:\Temp\ps.xlsx"
rm $file -ErrorAction Ignore

ps |
    where company |
    select Company,PagedMemorySize,PeakPagedMemorySize |
    Export-Excel $file -Show -AutoSize `
        -IncludePivotTable `
        -IncludePivotChart `
        -ChartType ColumnClustered `
        -PivotRows Company `
        -PivotData @{PagedMemorySize='sum';PeakPagedMemorySize='sum'} `
        -PivotDataToColumn

And here is the new chart view

4/7/2016

Made more methods fluent

$t=Get-Range 0 5 .2

$t2=$t|%{$_*$_}
$t3=$t|%{$_*$_*$_}

(New-Plot).
    Plot($t,$t, $t,$t2, $t,$t3).
    SetChartPosition("i").
    SetChartSize(500,500).
    Title("Hello World").
    Show()

3/31/2016

Thanks to redoz Multi Series Charts are now working

Also check out how you can create a table and then with Excel notation, index into the data for charting "Impressions[A]"

$data = @"
A,B,C,Date
2,1,1,2016-03-29
5,10,1,2016-03-29
"@ | ConvertFrom-Csv

$c = New-ExcelChart -Title Impressions `
    -ChartType Line -Header "Something" `
    -XRange "Impressions[Date]" `
    -YRange @("Impressions[B]","Impressions[A]")

$data |
    Export-Excel temp.xlsx -AutoSize -TableName Impressions -Show -ExcelChartDefinition $c

3/26/2016

Added NumberFormat parameter

$data |
    Export-Excel -Path $file -Show -NumberFormat '[Blue]$#,##0.00;[Red]-$#,##0.00'

3/18/2016

Added Get-Range, New-Plot and Plot Cos example
Updated EPPlus DLL. Allows markers to be changed and colored
Handles and warns if auto name range names are also valid Excel ranges

3/7/2016

Added Header and FirstDataRow for Import-Html

3/2/2016

Added GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual to New-ConditionalText

echo 489 668 299 777 860 151 119 497 234 788 |
    Export-Excel c:\temp\test.xlsx -Show `
    -ConditionalText (New-ConditionalText -ConditionalType GreaterThan 525)

2/22/2016

Import-Html using Lee Holmes Extracting Tables from PowerShell’s Invoke-WebRequest

2/17/2016

Added Conditional Text types of Equal and NotEqual
Phone #'s like '+33 011 234 34' will be now be handled correctly

Try PassThru

$file = "C:\Temp\passthru.xlsx"
rm $file -ErrorAction Ignore

$xlPkg = $(
    New-PSItem north 10
    New-PSItem east  20
    New-PSItem west  30
    New-PSItem south 40
) | Export-Excel $file -PassThru

$ws=$xlPkg.Workbook.Worksheets[1]

$ws.Cells["A3"].Value = "Hello World"
$ws.Cells["B3"].Value = "Updating cells"
$ws.Cells["D1:D5"].Value = "Data"

$ws.Cells.AutoFitColumns()

$xlPkg.Save()
$xlPkg.Dispose()

Invoke-Item $file

Result

1/18/2016

Added Conditional Text Formatting. Boe Prox posted about HTML Reporting, Part 2: Take Your Reporting a Step Further and colorized cells. Great idea, now part of the PowerShell Excel module.

1/7/2016

Added Get-ExcelSheetInfo - Great contribution from Johan Åkerström check him out on GitHub and Twitter

12/26/2015

Added NoLegend, Show-Category, ShowPercent for all charts including Pivot Charts
Updated PieChart, BarChart, ColumnChart and Line chart to work with the pipeline and added NoLegend, Show-Category, ShowPercent

12/17/2015

These new features open the door for really sophisticated work sheet creation.

Stay tuned for a blog post and examples.

Quick List

StartRow, StartColumn for placing data anywhere in a sheet
New-ExcelChart - Add charts to a sheet, multiple series for a chart, locate the chart anywhere on the sheet
AutoNameRange, Use functions and/or calculations in a cell
Quick charting using PieChart, BarChart, ColumnChart and more

10/20/2015

Big bug fix for version 3.0 PowerShell folks!

This technique fails in 3.0 and works in 4.0 and later.

$m="substring"
"hello".$m(2,1)

Adding .invoke works in 3.0 and later.

$m="substring"
"hello".$m.invoke(2,1)

A big thank you to DarkLite1 for adding the help to Export-Excel.

Added -HeaderRow parameter. Sometimes the heading does not start in Row 1.

10/16/2015

Fixes Export-Excel generates corrupt Excel file

10/15/2015

Import-Excel has a new parameter NoHeader. If data in the sheet does not have headers and you don't want to supply your own, Import-Excel will generate the property name.

Import-Excel now returns .Value rather than .Text

10/1/2015

Merged ValidateSet for Encoding and Extension. Thank you Irwin Strachan.

9/30/2015

Export-Excel can now handle data that is not an object

echo a b c 1 $true 2.1 1/1/2015 | Export-Excel c:\temp\test.xlsx -Show

dir -Name | Export-Excel c:\temp\test.xlsx -Show

9/25/2015

Hide worksheets Got a great request from forensicsguy20012004 to hide worksheets. You create a few pivotables, generate charts and then pivot table worksheets don't need to be visible.

Export-Excel now has a -HideSheet parameter that takes and array of worksheet names and hides them.

Example

Here, you create four worksheets named PM,Handles,Services and Files.

The last line creates the Files sheet and then hides the Handles,Services sheets.

$p = Get-Process

$p|select company, pm | Export-Excel $xlFile -WorkSheetname PM
$p|select company, handles| Export-Excel $xlFile -WorkSheetname Handles
Get-Service| Export-Excel $xlFile -WorkSheetname Services

dir -File | Export-Excel $xlFile -WorkSheetname Files -Show -HideSheet Handles, Services

Note There is a bug in EPPlus that does not let you hide the first worksheet created. Hopefully it'll resolved soon.

9/11/2015

Added Conditional formatting. See TryConditional.ps1 as an example.

Or, check out the short "How To" video.

8/21/2015

Now import Excel sheets even if the file is open in Excel. Thank you Francois Lachance-Guillemette

7/09/2015

For -PivotRows you can pass a hashtable with the name of the property and the type of calculation. Sum, Average, Max, Min, Product, StdDev, StdDevp, Var, Varp

Get-Service |
    Export-Excel "c:\temp\test.xlsx" `
        -Show `
        -IncludePivotTable `
        -PivotRows status `
        -PivotData @{status='count'}

6/16/2015 (Thanks Justin)

Improvements to PivotTable overwriting
Added two parameters to Export-Excel
- RangeName - Turns the data piped to Export-Excel into a named range.
- TableName - Turns the data piped to Export-Excel into an excel table.

Examples

Get-Process|Export-Excel foo.xlsx -Verbose -IncludePivotTable -TableName "Processes" -Show
Get-Process|Export-Excel foo.xlsx -Verbose -IncludePivotTable -RangeName "Processes" -Show

5/25/2015

Fixed null header problem

5/17/2015

Added three parameters:
- FreezeTopRow - Freezes the first row of the data
- AutoFilter - Enables filtering for the data in the sheet
- BoldTopRow - Bolds the top row of data, the column headers

Example

Get-CimInstance win32_service |
    select state, accept*, start*, caption |
    Export-Excel test.xlsx -Show -BoldTopRow -AutoFilter -FreezeTopRow -AutoSize

5/4/2015

Published to PowerShell Gallery. In PowerShell v5 use Find-Module importexcel then Find-Module importexcel | Install-Module

4/27/2015

datetime properties were displaying as ints, now are formatted

4/25/2015

Now you can create multiple Pivot tables in one pass
- Thanks to pscookiemonster, he submitted a repro case to the EPPlus CodePlex project and got it fixed

Example

$ps = ps

$ps |
    Export-Excel .\testExport.xlsx  -WorkSheetname memory `
        -IncludePivotTable -PivotRows Company -PivotData PM `
        -IncludePivotChart -ChartType PieExploded3D
$ps |
    Export-Excel .\testExport.xlsx  -WorkSheetname handles `
        -IncludePivotTable -PivotRows Company -PivotData Handles `
        -IncludePivotChart -ChartType PieExploded3D -Show

4/20/2015

Included and embellished Claus Nielsen function to take all sheets in an Excel file workbook and create a text file for each ConvertFrom-ExcelSheet
Renamed Export-MultipleExcelSheets to ConvertFrom-ExcelSheet

4/13/2015

You can add a title to the Excel "Report" Title, TitleFillPattern, TitleBold, TitleSize, TitleBackgroundColor
- Thanks to Irwin Strachan for this and other great suggestions, testing and more

4/10/2015

Renamed AutoFitColumns to AutoSize
Implemented Export-MultipleExcelSheets
Implemented -Password for a worksheet
Replaced -Force switch with -NoClobber switch
Added examples for Get-Help
If Pivot table is requested, that sheet becomes the tab selected

4/8/2015

Implemented exporting data to named sheets via the -WorkSheetname parameter.

Examples - gsv | Export-Excel .\test.xlsx -WorkSheetname Services

dir -file | Export-Excel .\test.xlsx -WorkSheetname Files

ps | Export-Excel .\test.xlsx -WorkSheetname Processes -IncludePivotTable -Show -PivotRows Company -PivotData PM

Convert (All or Some) Excel Sheets to Text files

Reads each sheet in TestSheets.xlsx and outputs it to the data directory as the sheet name with the extension .txt

ConvertFrom-ExcelSheet .\TestSheets.xlsx .\data

Reads and outputs sheets like Sheet10 and Sheet20 form TestSheets.xlsx and outputs it to the data directory as the sheet name with the extension .txt

ConvertFrom-ExcelSheet .\TestSheets.xlsx .\data sheet?0

Example Adding a Title

You can set the pattern, size and of if the title is bold.

$p=@{
    Title = "Process Report as of $(Get-Date)"
    TitleFillPattern = "LightTrellis"
    TitleSize = 18
    TitleBold = $true

    Path  = "$pwd\testExport.xlsx"
    Show = $true
    AutoSize = $true
}

Get-Process |
    Where Company | Select Company, PM |
    Export-Excel @p

Example Export-MultipleExcelSheets

$p = Get-Process

$DataToGather = @{
    PM        = {$p|select company, pm}
    Handles   = {$p|select company, handles}
    Services  = {gsv}
    Files     = {dir -File}
    Albums    = {(Invoke-RestMethod http://www.dougfinke.com/PowerShellfordevelopers/albums.js)}
}

Export-MultipleExcelSheets -Show -AutoSize .\testExport.xlsx $DataToGather

NOTE If the sheet exists when using -WorkSheetname parameter, it will be deleted and then added with the new data.

Get-Process Exported to Excel

Total Physical Memory Grouped By Company

Importing data from an Excel spreadsheet

You can also find EPPLus on Nuget.

Known Issues

Using -IncludePivotTable, if that pivot table name exists, you'll get an error.
- Investigating a solution
- Workaround delete the Excel file first, then do the export

Author: dfinke
Source Code: https://github.com/dfinke/ImportExcel
License: Apache-2.0 License

#excel #powershell

Sid Strosin

1595897400

Auto-Documenting a Python Project Using Sphinx

While thorough documentation is necessary, it’s often put on the back burner and looked upon as a chore and a low-priority task. As a developer, it’s easy to fall back on the mindset of “why document the code when you, the author, know exactly what it’s doing?” When the code is rapidly changing, keeping the docs up to date becomes an even more substantial burden.

Luckily, manually writing out documentation is not required due to the capabilities of Sphinx, a tool that automatically generates documentation from the docstrings in your code.

Below is a step-by-step guide to easily auto-generate clean and well-organized documentation from Python code using Sphinx.

#sphinx #documentation #python