Installation and use¶
To install the CodeChat System, install the CodeChat Server and a CodeChat extension or plugin, along with optional external renderers you desire.
CodeChat Server Installation¶
To install the CodeChat Server:
Windows¶
Open up PowerShell in Admin mode.
Run the following command:
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/bjones1/CodeChat_system/master/CodeChat_Server/windows_installer.ps1 -UseBasicParsing).Content | powershell -ExecutionPolicy Bypass -
in PowerShell.
Linux¶
Highlight this entire command:
curl -sSL https://raw.githubusercontent.com/bjones1/CodeChat_system/master/CodeChat_Server/linux_installer.sh | bash -
and press Ctrl-C to copy. Go to the terminal window and press Ctrl-Shift-V. Press Enter.
Mac¶
Make sure pip, the Python installer, is up to date: at the terminal, type
python3 -m pip install --user --upgrade pip
.Create a virtual environment named codechat by typing
python3 -m venv codechat
. This keeps the installation of the CodeChat System from interfering with other installed Python programs and vice versa.Activate this virtual environment by typing
source codechat/bin/activate
.Install the CodeChat Server with the Sphinx renderer by typing
python3 -m pip install --upgrade CodeChat_Server Sphinx
.Determine the location of the installed CodeChat Server by typing
which CodeChat_Server
. You’ll need to enter this path when setting up the CodeChat plugin/extension in your IDE.Install the CodeChat extension/plugin for your IDE or text editor.
To update the CodeChat Server, repeat steps 1, 5, and 6.
Troubleshooting¶
Windows¶
- If Powershell shows an error informing you that running scripts is forbidden on your system, follow these additional steps:
Open Powershell in administrator mode
type
Set-ExecutionPolicy RemoteSigned
Run Powershell Script again
If you wish to install your own version of Python, make sure you are checking the Add to PATH checkbox on installation
Linux¶
CodeChat requires an up-to-date installation of Python 3.
CodeChat extension/plugin installation¶
Install a CodeChat plugin or extension to use the CodeChat System (the final required step of the installation steps above).
Renderers¶
Renderers transform a textual source document into HTML, which the CodeChat System can then display. The CodeChat System includes several renderers; you may also optionally install additional renderers.
Included renderers¶
The CodeChat Server includes built-in renderers for reStructuredText, Markdown, and (x)HTML; simply open any .rst
, .md
, or .(x)htm(l)
document and see it rendered live! In addition, the built-in CodeChat renderer allows you to transform source code in many languages to a beautifully-formatted web page; likewise, simply open a source file to see it rendered live.
Additional renderers¶
The CodeChat System has (limited) support for Pandoc. Install this and ensure it’s in the path; the CodeChat Server will then use it to render a wider range of files.
The CodeChat System also works with project-based external renderers, by providing a CodeChat project configuration file (example) for that renderer. The templates/
directory provides templates demonstrating a basic project for the following external renderers; each template includes the correct CodeChat project configuration file.
Templates¶
Sphinx (rendered template) – note that this documentation is produced using CodeChat with Sphinx; see codechat_config.yaml - Configuration for a CodeChat project and conf.py - The CodeChat System documentation configuration. Sphinx is the primary platform for literate programming with CodeChat; installing it is highly recommended. The install instructions install Sphinx by default.
To use these templates:
Install the external renderer.
Make a copy of the appropriate template. These files are available via Github, installed with the CodeChat Server via
pip
/your favorite Python package manager, and also available via the “show source” link on these web pages.Open a file from the copied template in the CodeChat System to edit and render them.
To use the CodeChat System with an external renderer not listed above:
Install the desired external renderer.
Create a new project following the external renderer’s instructions.
Place a CodeChat project configuration file at the root of this newly-created project.
Open any file supported by the external renderer in this newly created project. The CodeChat System will automatically render it.
Use¶
See the home page for a brief overview of the CodeChat Client GUI.