diff --git a/INSTALLATION.md b/INSTALLATION.md index 3ceb817e3..ede7dbffe 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -1,77 +1,27 @@ # Installation -There are three steps to follow if you want to generate the full content of the -Taipy documentation: +To see the changes you make to the documentation in a web browser, follow these steps: -1. Locally copy the mandatory files from other repositories. +### 1. Copy locally the source files from the Taipy repositories - Because source files (where the Reference Manual information is stored) are - spread among different directories, those files need to be locally copied - before you run MkDocs.
- This can be done quickly and safely using the Python script `fetch_source_files.py` - that you can find in the `tools` directory. +In a terminal at the root of this repository, run: +```bash +python tools/fetch_source_files.py develop +``` - Run the script when your current directory is the root of the `taipy-doc` checkout: - ``` - python tools/fetch_source_files.py - ``` +### 2. Generate the documentation from the source files - The script can copy the source files from two locations: +```bash +pip install pipenv +pipenv install --dev +pipenv shell +pipenv run python tools/setup_generation.py +``` - - your local filesystem (next to the current directory `taipy-doc`, you would have - cloned the repositories that make the whole Taipy product: `taipy-config`, - `taipy-core`, `taipy-getting-started`, `taipy-gui` and `taipy-rest`).
- - the Taipy repositories on GitHub. +### 3. Launch the web server - By default, the script will copy all repositories from a local clone. Before files - are copied, a `git pull` command is launched from each local clone directory, in - order to update the files locally.
- You can prevent the script from doing so using the `--no_pull` option. +```bash +mkdocs serve +``` - To specify that you want to clone the repositories from GitHub, you can - indicate the version of Taipy you wish to clone.
- If you want to build the documentation set for Taipy 2.0, you will run: - `python tools/fetch_source_files.py 2.0`.
- You can also indicate a specific tag (i.e., `python tools/fetch_source_files.py 1.0.2`).
- To use the `develop` branch, replace the version number with the string "develop" - (i.e., `python tools/fetch_source_files.py develop`). - - See the help text (`python tools/fetch_source_files.py --help`) for more information. - - After the script has run successfully, you will notice that two new directories are created - in the root directory: `taipy` and `gui`. There are where mandatory files are copied. Git - ignores these two directories, and you should not bother with them. - -2. Generate the Reference Manual and Visual Elements' documentation files. - - The Reference Manual and the documentation for the Visual Elements of the `taipy-gui` module - are generated from source files copied from a set of repositories.
- To generate all mandatory files, execute the Python script `setup_generation.py` located - in the `tools` directory. Run the script when your current directory is the root - of the `taipy-doc` checkout: - ``` - # Install pipenv if necessary - pip install pipenv - # Install the mandatory Python modules from Pipfile to the virtual env - pipenv install --dev - # Set the environment for the shell - pipenv shell - # Run the setup - pipenv run python tools/setup_generation.py - ``` - -3. Generate the documentation set.
- When all files are copied and generated, you can finally use MkDocs to generate the - documentation set. You can use any of the three predefined generation modes: - - - `serve`: This is a great way to let MkDocs generate the documentation and - locally run a web server that lets you watch your changes impact on the fly. - - - `build`: Generates the documentation set as a whole hierarchy of files (in - `site`). These files can be copied wherever you need to deploy them. - - - `gh-deploy`: Generates and deploys the documentation set as a _GitHub Pages_ - site to publish the result of the documentation build. - - To generate the doc, and assuming you are still within the *pipenv shell* context, - you will run: `mkdocs ` (i.e. `mkdocs serve`). +This will launch a web server with the local documentation. Everytime you save a file, the server will automatically relaunch the web server so you can see your changes. \ No newline at end of file