From 53ed6d7d1e678d7486337ce67a2f17b30bac21ac Mon Sep 17 00:00:00 2001 From: nodiscc Date: Thu, 26 Jan 2017 18:52:54 +0100 Subject: Generate HTML documentation using MkDocs (WIP) MkDocs is a static site generator geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML file. * http://www.mkdocs.org/ * http://www.mkdocs.org/user-guide/configuration/ Ref. #312 * remove pandoc-generated HTML documentation * move markdown doc to doc/md/, * mkdocs.yml: * generate HTML doc in doc/html * add pages TOC/ordering * use index.md as index page * Makefile: remove execute permissions from generated files * Makefile: rewrite htmlpages GFM to markdown conversion using sed: awk expression aslo matched '][' which causes invalid output on complex links with images or code blocks * Add mkdocs.yml to .gitattributes, exclude this file from release archives * Makefile: rename: htmldoc -> doc_html target * run make doc: pull latest markdown documentation from wiki * run make htmlpages: update html documentation --- doc/Upgrade-and-migration.md | 186 ------------------------------------------- 1 file changed, 186 deletions(-) delete mode 100644 doc/Upgrade-and-migration.md (limited to 'doc/Upgrade-and-migration.md') diff --git a/doc/Upgrade-and-migration.md b/doc/Upgrade-and-migration.md deleted file mode 100644 index d36eb862..00000000 --- a/doc/Upgrade-and-migration.md +++ /dev/null @@ -1,186 +0,0 @@ -#Upgrade and migration -## Preparation -### Note your current version - -If anything goes wrong, it's important for us to know which version you're upgrading from. -The current version is present in the `version.php` file. - -### Backup your data - -Shaarli stores all user data under the `data` directory: -- `data/config.php` - main configuration file -- `data/datastore.php` - bookmarked links -- `data/ipbans.php` - banned IP addresses -- `data/updates.txt` - contains all automatic update to the configuration and datastore files already run - -See [Shaarli configuration](Shaarli-configuration.html) for more information about Shaarli resources. - -It is recommended to backup this repository _before_ starting updating/upgrading Shaarli: -- users with SSH access: copy or archive the directory to a temporary location -- users with FTP access: download a local copy of your Shaarli installation using your favourite client - -### Migrating data from a previous installation -As all user data is kept under `data`, this is the only directory you need to worry about when migrating to a new installation, which corresponds to the following steps: - -- backup the `data` directory -- install or update Shaarli: - - fresh installation - see [Download and installation](Download-and-installation.html) - - update - see the following sections -- check or restore the `data` directory - -## Recommended : Upgrading from release archives -All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.[](.html) - -We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and installation](Download-and-installation.html) for `git` complete instructions. - -Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory! - -After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli-configuration.html) for more details). - -## Upgrading with Git -### Updating a community Shaarli -If you have installed Shaarli from the [community Git repository](Download#clone-with-git-recommended), simply [pull new changes](https://www.git-scm.com/docs/git-pull) from your local clone:[](.html) - -```bash -$ cd /path/to/shaarli -$ git pull - -From github.com:shaarli/Shaarli - * branch master -> FETCH_HEAD -Updating ebd67c6..521f0e6 -Fast-forward - application/Url.php | 1 + - shaarli_version.php | 2 +- - tests/Url/UrlTest.php | 1 + - 3 files changed, 3 insertions(+), 1 deletion(-) -``` - -Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html) - -```bash -$ composer install --no-dev - -Loading composer repositories with package information -Updating dependencies - - Installing shaarli/netscape-bookmark-parser (v1.0.1) - Downloading: 100% -``` - -### Migrating and upgrading from Sebsauvage's repository -If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy.[](.html) - -The following guide assumes that: -- you have a basic knowledge of Git [branching](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) and [remote repositories](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)[](.html) -- the default remote is named `origin` and points to Sebsauvage's repository -- the current branch is `master` - - if you have personal branches containing customizations, you will need to [rebase them](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) after the upgrade; beware though, a lot of changes have been made since the community fork has been created, so things are very likely to break![](.html) -- the working copy is clean: - - no versioned file has been locally modified - - no untracked files are present - -#### Step 0: show repository information -```bash -$ cd /path/to/shaarli - -$ git remote -v -origin https://github.com/sebsauvage/Shaarli (fetch) -origin https://github.com/sebsauvage/Shaarli (push) - -$ git branch -vv -* master 029f75f [origin/master] Update README.md[](.html) - -$ git status -On branch master -Your branch is up-to-date with 'origin/master'. -nothing to commit, working directory clean -``` - -#### Step 1: update Git remotes -``` -$ git remote rename origin sebsauvage -$ git remote -v -sebsauvage https://github.com/sebsauvage/Shaarli (fetch) -sebsauvage https://github.com/sebsauvage/Shaarli (push) - -$ git remote add origin https://github.com/shaarli/Shaarli -$ git fetch origin - -remote: Counting objects: 3015, done. -remote: Compressing objects: 100% (19/19), done. -remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550 -Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done. -Resolving deltas: 100% (1899/1899), completed with 48 local objects. -From https://github.com/shaarli/Shaarli - * [new branch] master -> origin/master[](.html) - * [new branch] stable -> origin/stable[](.html) -[...][](.html) - * [new tag] v0.6.4 -> v0.6.4[](.html) - * [new tag] v0.7.0 -> v0.7.0[](.html) -``` - -#### Step 2: use the stable community branch - -```bash -$ git checkout origin/stable -b stable -Branch stable set up to track remote branch stable from origin. -Switched to a new branch 'stable' - -$ git branch -vv - master 029f75f [sebsauvage/master] Update README.md[](.html) -* stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5[](.html) -``` - -Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html) - -```bash -$ composer install --no-dev - -Loading composer repositories with package information -Updating dependencies - - Installing shaarli/netscape-bookmark-parser (v1.0.1) - Downloading: 100% -``` - -Optionally, you can delete information related to the legacy version: - -```bash -$ git branch -D master -Deleted branch master (was 029f75f). - -$ git remote remove sebsauvage - -$ git remote -v -origin https://github.com/shaarli/Shaarli (fetch) -origin https://github.com/shaarli/Shaarli (push) - -$ git gc -Counting objects: 3317, done. -Delta compression using up to 8 threads. -Compressing objects: 100% (1237/1237), done. -Writing objects: 100% (3317/3317), done. -Total 3317 (delta 2050), reused 3301 (delta 2034)to -``` - -#### Step 3: configuration -After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli-configuration.html) for more details). - -## Troubleshooting - -If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to. - -### You must specify an integer as a key - -In `v0.8.1` we changed how link keys are handled (from timestamps to incremental integers). -Take a look at `data/updates.txt` content. - -#### `updates.txt` contains `updateMethodDatastoreIds` - -Try to delete it and refresh your page while being logged in. - -#### `updates.txt` doesn't exists or doesn't contain `updateMethodDatastoreIds` - - 1. Create `data/updates.txt` if it doesn't exist. - 2. Paste this string in the update file `;updateMethodRenameDashTags;` - 3. Login to Shaarli. - 4. Delete the update file. - 5. Refresh. -- cgit v1.2.3