Download the PHP package garvinhicking/typo3-documentation-browsersync without Composer

On this page you can find all versions of the php package garvinhicking/typo3-documentation-browsersync. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package typo3-documentation-browsersync

typo3-documentation-browsersync

TL;DR:

Introduction

Standalone project (NodeJS, browsersync) to render and hot-reload changes in TYPO3 ReST documentation to your browser window.

The files are rendered through the official https://github.com/TYPO3-documentation/render-guides project. Please see https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/WritingDocForExtension/Index.html for more information on TYPO3 documentations.

This project exists to be build and used as a Docker container. It's not meant to run natively, because it would require a lot of dependencies (PHP, composer, NodeJS, nvm) and the underlying TYPO3-Documentation/render-guides project is NOT SUPPORTED as a Composer package, making native use impossible.

The Docker container provides a proxy server that returns (proxies) your rendered ReST documentation (as HTML) to a browser. Any change you make to the ReST-files will automatically trigger a reload of your browser window.

This allows you to have some kind of "WYSIWYG" display of your documentation, without the need to manually reload browser windows or render documentation time and again. It will all happen on demand.

ReST is very dependent on the used renderer and its capabilities, so you cannot really have a WYSIWYG editor for ReST files. A tool like this is, what comes closest to editing files and directly seeing the impact of it.

General Usage

This project depends on the ability to execute Docker Containers on your host.

You can also use Podman, if you prefer. Replace the docker commands with podman in that case.

You can use the provided Docker container within any project directory:

This starts a server to listen on localhost port 5173, so you can point your browser to a URL like this:

Output

The Docker container will show you the vite console of the running server, you can interact with it. It will run until you enter q ("quit") or use Ctrl-C to end the process.

Whenever you make changes to either the .rst or .html files, you will see console output about what is performed.

Demo project

There's a simple demo project which showcases how to use it with a dummy Documentation directory

https://github.com/garvinhicking/demo-typo3-documentation-browsersync

Parameters of the "docker run" command explained

The docker command above starts the Docker container ghcr.io/garvinhicking/typo3-documentation-browsersync:latest with these options:

If you want to know what is contained inside the Docker container, please check out the Dockerfile used to build it:

https://github.com/garvinhicking/typo3-documentation-browsersync/blob/main/Dockerfile

Once the Docker is up and running, it will watch the Directory Documentation for any changes, trigger rendering and proxy the created HTML to your browser.

Changing default port and directories

You can provide these environment variables, if you want to run on non-default ports and different directories:

So a full docker run command utilizing this, and directly opening a browser window with the URL, would look like:

See the file alias.sh in this repository, you could place these lines into an alias of your Shell, or place it in a /usr/local/bin/render-wysiwyg.sh file and call it.

The reason why the environment variables are called twice is because the docker run command already needs to access them, and then they also need to be propagated into the docker container as well.

HEADS UP: WRITE-actions to files on the HOST-side!

IMPORTANT: The rendering process will CHANGE AND OVERWRITE FILES in the output-directory (Documentation-GENERATED-temp). Be sure to only execute the container if there are no files in there that may not be overwritten!

If the directory is empty, a first-time rendering will be started when the Docker container is started.

If the input directory is missing, the watch server will fail.

The input directory (Documentation) is only used for reading.

Building a local container

Via GitHub Actions, this project creates a Docker Container on ghcr.io via a multi-stage build process.

The contained Dockerfile performs this:

If you check out this project, you can build the Docker container yourself:

and then execute it via:

Notes

A first idea was to also provide a native way (without Docker) to perform rendering and proxying locally. The depedency chain for this was harsh, and the render-guides project does not support being used as a dependency.

So this is currently "beyond scope". The repository has a base composer.json file and abilities to run locally, but this is just a stub.

The only vital things inside this project are:

Alternatives (PHPStorm)

PHPStorm actually offers a cool way to create a local proxy server on its own; when you pick a rendered HTML file and right-click Open in > Browser > Default it will open a browser window on your host and show the contents of the HTML file, and also have hot-reload capability. So when you change anything in the HTML file, the PHPStorm proxy server will directly reload your output, too. It will however NOT render the ReST files automatically, when such a file is edited.

If your OS supports inotifywait (on Linux), you could use this:

to automatically "watch" for any change on ReST files inside the Documentation folder, then re-render the HTML, which would then automatically reload your browser window.

Sadly, inotifywait is not available on macOS and the alternative to build a custom PHP pecl inotify package-enabled tool was beyond my personal scope, as well as using alternate tools like fswatch.

I wanted to have an easy way for anyone to preview changes, so I wanted to not require PHPStorm or a specific inotify-enabled OS.

Instead, the NodeJS ecosystem provides a browsersync package that does all of the needed watching and proxying. I coupled this with vite, because alternatives like gulp or grunt are outdated and report many security issues on their dependencies.


All versions of typo3-documentation-browsersync with dependencies

PHP Build Version
Package Version
Requires php Version ^8.2
t3docs/render-guides Version dev-main
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package garvinhicking/typo3-documentation-browsersync contains the following files

Loading the files please wait ....