Auto-update from Github Actions Workflow

Deployed from commit c30a7c9 (refs/tags/v2.17.0)
pcdshub · Sep 16, 2024 · dee0f8b · dee0f8b
1 parent 3aafc37
commit dee0f8b
Show file tree

Hide file tree

Showing 59 changed files with 13,560 additions and 3 deletions.
diff --git a/index.html b/index.html
@@ -1,9 +1,9 @@
 <!DOCTYPE html>
 <html>
   <head>
-    <meta http-equiv="Refresh" content="0; url=v2.16.0" />
+    <meta http-equiv="Refresh" content="0; url=v2.17.0" />
   </head>
   <body>
-    <p>Go to the <a href="v2.16.0">default documentation</a>.</p>
+    <p>Go to the <a href="v2.17.0">default documentation</a>.</p>
   </body>
 </html>
diff --git a/v2.17.0/_sources/getting_started.rst.txt b/v2.17.0/_sources/getting_started.rst.txt
@@ -0,0 +1,68 @@
+Getting Started
+===============
+
+General Usage
++++++++++++++
+pytmc has various capabilities that can be accessed using the top-level ``pytmc`` program:
+
+   1. Generating EPICS database files (.db) based on a Beckhoff TwinCAT ``.tmc`` file (``pytmc db``)
+   2. Introspecting ``.tmc`` files for their symbols and data types ( ``pytmc debug`` and ``pytmc types``)
+   3. Generating full EPICS IOCs based on a provided template (``pytmc iocboot`` and ``pytmc stcmd``)
+   4. Parsing, introspecting, and summarizing full TwinCAT projects (``pytmc summary``)
+   5. Outlining any TwinCAT XML file (``pytmc xmltranslate``)
+
+In order for pytmc to work properly, the TwinCAT project and its
+libraries require annotation. The resulting IOC depends upon EPICS ADS driver. This
+driver is provided by the `European Spallation Source
+<https://europeanspallationsource.se/>`_ and is hosted on their `bitbucket page
+<https://bitbucket.org/europeanspallationsource/m-epics-twincat-ads>`_.
+
+Marking the TwinCAT project
++++++++++++++++++++++++++++
+Marking the TwinCAT project determines how the EPICS record will be generated.
+The marking process uses custom attribute pragmas to designate variables for
+pytmc to process. The pragma should be applied just above the declaration of
+the variable you wish to mark. You can read more about the TwinCAT pragma
+system `here
+<https://infosys.beckhoff.com/english.php?content=../content/1033/tc3_plc_intro/9007201784297355.html&id=>`_.
+
+Best practices for SLAC projects are documented in the `PCDS confluence page
+<https://confluence.slac.stanford.edu/display/PCDS/TwinCAT+3+Git+Setup+and+Best+Practices>`_.
+
+Having issues with multiline pragmas and related things? See the `PCDS flight
+rules
+<https://confluence.slac.stanford.edu/display/PCDS/Beckhoff+Flight+Rules>`_.
+
+
+Python Usage
+++++++++++++
+Once installed pytmc and its components can be imported into a python program
+or shell like any normal python package. Consult the source code documentation
+for specifics.
+
+
+Full IOC Creation
++++++++++++++++++
+
+PCDS has recently focused its efforts on `ads-deploy
+<https://github.com/pcdshub/ads-deploy>`_, for seamless development and
+deployment of IOCs directly from the TwinCAT IDE. Behind the scenes, ads-deploy
+takes care of the following steps using a docker container:
+
+.. code-block:: sh
+
+   $ git clone https://github.com/pcdshub/ads-ioc /path/to/ads-ioc
+   $ pytmc iocboot /path/to/plc.tsproj /path/to/ads-ioc/iocBoot/templates/
+   # Creates directories: ioc-plc-name1, ioc-plc-name2, ...
+   # Creates Makefiles: ioc-plc-name/Makefile
+
+   $ cd ioc-plc-name
+   $ vim Makefile
+   # Customize - if necessary - to add more db files or change pytmc stcmd options
+
+   $ make
+   # Shells out to pytmc stcmd;
+   # Creates st.cmd, ioc-plc-name.db, envPaths
+
+   $ ./st.cmd
+   # Runs IOC
diff --git a/v2.17.0/_sources/index.rst.txt b/v2.17.0/_sources/index.rst.txt
@@ -0,0 +1,31 @@
+.. pytmc documentation master file, created by
+   sphinx-quickstart on Thu Dec  7 12:54:14 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to pytmc's documentation!
+=================================
+.. image:: https://travis-ci.org/pcdshub/pytmc.svg?branch=master
+       :target: https://travis-ci.org/pcdshub/pytmc
+
+Pytmc helps developers automatically generate ADS based Epics records files
+from Beckhoff's TwinCAT3 projects.
+
+Pytmc is developed with these `guidelines
+<https://pcdshub.github.io/development.html>`_ in mind.
+
+The source code is hosted on `github <https://github.com/pcdshub/pytmc>`_.
+
+Issues and requests can be posted on the `github issue tracker
+<https://github.com/pcdshub/pytmc/issues>`_. Use the ``bug`` tag for issues
+with intended features and the ``enhancement`` tag can be used for feature
+requests. The ``question`` tag will be treated like an 'enhancements' tag for
+the documentation but regular questions can be posted there as well.
+
+.. toctree::
+   :maxdepth: 4
+   :caption: Contents:
+
+   user_guide.rst
+   source_code.rst
+   release_notes.rst
diff --git a/v2.17.0/_sources/installation.rst.txt b/v2.17.0/_sources/installation.rst.txt
@@ -0,0 +1,101 @@
+Installation
+============
+
+Obtaining the code
+++++++++++++++++++
+Download the code via the tagged releases posted on the `github releases page
+<https://github.com/pcdshub/pytmc/releases>`_ or by cloning the source code
+with the following:
+
+.. code-block:: sh
+
+   $ git clone https://github.com/pcdshub/pytmc.git
+
+Installing in an environment
+++++++++++++++++++++++++++++
+Create a python virtual environment using conda and install the pytmc in that
+environment.
+
+Begin by creating an environment and replacing [env-name] with the
+name of your environment. If you're installing pytmc in a preexisting
+environment, you may skip this step.
+
+.. code-block:: sh
+
+   $ conda create --name [env-name]
+
+Activate your environment.
+
+.. code-block:: sh
+
+   $ source activate [env-name]
+
+Install pip in the current environment if it is not already. If pip is not
+installed in your environment, the system will default to using pip in the root
+environment. When the root environment's version of pip is used. Pip will
+attempt to install the package in the root envirnoment as well.
+
+.. code-block:: sh
+
+   $ conda install pip
+
+After cloning or unzipping the package, navigate to the base directory of
+pytmc. There you will find a file titled ``setup.py`` and another titles
+``requirements.txt``. Run the following commands from this directory. Make sure
+to install pip in this conda environment prior to installing tools with pip.
+Using pip in an environment lacking a pip installation will install pytmc in
+your root environment.
+
+.. code-block:: sh
+
+   $ # Install pytmc's dependencies
+   $ pip install -r requirements.txt
+   $ # Install pytmc to your environment
+   $ pip install .
+
+.. note::
+
+   The last line in the code snippet above has a '.' at the end. It is very
+   difficult to see with certain browsers.
+
+
+Testing the installation
+++++++++++++++++++++++++
+If you've followed the previous steps correctly, pytmc should be installed now.
+This can be tested by seeing if the following bash commands can be found.
+
+.. code-block:: sh
+
+   $ pytmc --help
+
+Alternatively, a python shell can be opened and you can attempt to import
+pytmc.
+
+.. code-block:: python
+
+   >>> import pytmc
+
+.. note::
+   While all of these instructions should work with python environments
+   managed by virtualenv and pipenv, only conda has been tested.
+
+
+Installing for development
+++++++++++++++++++++++++++
+To develop pytmc it is best to use a development install. This allows changes
+to the code to be immediately reflected in the program's functionality without
+needing to reinstall the code.This can be done by following the `Installing in
+an environment`_ section but with one change. The following code snippet should
+be removed:
+
+.. code-block:: sh
+
+   $ # Don't use this step for a development install
+   $ pip install .
+
+In place of the removed command, use the following to do a development install.
+
+.. code-block:: sh
+
+   $ # Use this command instead
+   $ pip install -e .