From f4df12eb3fa53d3f8162306260c855c624dad89b Mon Sep 17 00:00:00 2001 From: Hydrus Network Developer Date: Tue, 22 Feb 2022 17:35:58 -0600 Subject: [PATCH] Some basic docs updates --- README.md | 2 +- Readme.txt | 5 ----- docs/PTR.md | 6 +++--- docs/about_docs.md | 31 +++++++++++++---------------- docs/changelog.md | 4 ++-- docs/getting_started_installing.md | 2 ++ docs/old_changelog.html | 10 +++++----- docs/privacy.md | 4 ++-- mkdocs.yml | 2 +- requirements_macos_build.txt | 1 + requirements_ubuntu_build.txt | 1 + requirements_windows_build.txt | 1 + static/build_files/docker/README.md | 2 +- 13 files changed, 34 insertions(+), 37 deletions(-) delete mode 100644 Readme.txt diff --git a/README.md b/README.md index 3c956b45..3b0fc4e1 100755 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ I am continually working on the software and try to put out a new release every This github repository is currently a weekly sync with my home dev environment, where I work on hydrus by myself. **Feel free to fork and do whatever you like with my code, but please do not make pull requests.** The [issue tracker here on Github](https://github.com/hydrusnetwork/hydrus/issues) is active and run by blessed volunteer users. I am not active here on Github, and I have difficulty keeping up with social media in general, but I welcome feedback of any sort and will eventually catch up with and reply to email, the 8chan or Endchan, tumblr, twitter, or the discord. -The client can do quite a lot! Please check out the help inside the release or [here](https://hydrusnetwork.github.io/hydrus/), which includes a comprehensive getting started guide. +The client can do quite a lot! Please check out the help inside the release or [here](https://hydrusnetwork.github.io/hydrus/), which includes a comprehensive getting started guide. If you are running from source and would like a local copy of the help, check [here](https://hydrusnetwork.github.io/hydrus/about_docs.html)! A rudimentary documentation for the [container](https://github.com/hydrusnetwork/hydrus/pkgs/container/hydrus) setup can be found [here](https://github.com/hydrusnetwork/hydrus/blob/master/static/build_files/docker/README.md). diff --git a/Readme.txt b/Readme.txt deleted file mode 100644 index 56c53a2b..00000000 --- a/Readme.txt +++ /dev/null @@ -1,5 +0,0 @@ -If you are reading this, you probably extracted rather than installed, so you were not prompted to read the help. - -The hydrus client can do a lot, so do please go into the help folder and open up index.html so you don't get lost. Thanks! - -I use a number of the Silk Icons by Mark James at famfamfam.com. \ No newline at end of file diff --git a/docs/PTR.md b/docs/PTR.md index 23478586..3d381403 100644 --- a/docs/PTR.md +++ b/docs/PTR.md @@ -8,7 +8,7 @@ or *Myths and facts about the Public Tag Repository* ## What is the PTR? Short for Public Tag Repository, a now community managed repository of tags. Locally it acts as a tag service, just like `my tags`. At the time of writing 54 million files have tags on it. The PTR only store the sha256 hash and tag mappings of a file, not the files themselves or any non-tag meta data. In other words: If you don not see it in the tag list then it is not stored. -Most of the things in this document also applies to [self-hosted servers](https://hydrusnetwork.github.io/hydrus/help/server.html), except for tag guidelines. +Most of the things in this document also applies to [self-hosted servers](https://hydrusnetwork.github.io/hydrus/server.html), except for tag guidelines. ## Connecting to the PTR The easiest method is to use the built in function, found under `help -> add the public tag repository`. For adding it manually, if you so desire, read the Hydrus help document on [access keys](access_keys.md). @@ -16,7 +16,7 @@ If you are starting out completely fresh you can also download a fully synced cl Once you are connected Hydrus will proceed to download and then process the update files. The progress of this can be seen under `services -> review services -> remote -> tag repositories -> public tag repository`. Here you can view its status, your account (the default account is a shared public account. Currently only janitors and the administrator have personal accounts), tag status, and how synced you are. Being behind on the sync by a certain amount makes you unable to push tags and petitions until you are caught up again. ## How does it work? -For something to end up on the PTR it has to be pushed there. Tags can either be entered into the tag service manually by the user through the `manage tags` window, or be routed there by a parser when downloading files. See [parsing tags](https://hydrusnetwork.github.io/hydrus/help/getting_started_downloading.html). Once tags have been entered into the PTR tag service they are pending until pushed. This is indicated by the `pending ()` that will appear between `tags` and `help` in the menu bar. Here you can chose to either push your changes to the PTR or discard them. +For something to end up on the PTR it has to be pushed there. Tags can either be entered into the tag service manually by the user through the `manage tags` window, or be routed there by a parser when downloading files. See [parsing tags](https://hydrusnetwork.github.io/hydrus/getting_started_downloading.html). Once tags have been entered into the PTR tag service they are pending until pushed. This is indicated by the `pending ()` that will appear between `tags` and `help` in the menu bar. Here you can chose to either push your changes to the PTR or discard them. - Adding tags pass automatically. - Deleting (petitioning) tags requires janitor action. @@ -95,4 +95,4 @@ When making parents, make sure it's an always factually correct relationship. `c `meta:` : This namespace is used for information that isn't visible in the image itself or where you might need to go to the source. Some examples include: third-party edit, paid reward (patreon/enty/gumroad/fantia/fanbox), translated, commentary, and such. **What you know about the image.** -Namespaces not listed above are not "supported" by the janitors and are liable to get siblinged out, removed, and/or mocked if judged being bad and annoying enough to justify the work. Do not take this to mean that all un-listed namespaces are bad, some are created and used by parsers to indicate where an image came from which can be helpful if somebody else wants to fetch the original or check source tags against the PTR tags. But do exercise some care in what you put on the PTR if you use custom namespaces. Recently `clothing:` was removed due to being disliked, no booru using it, and the person(s) pushing for it seeming to have disappeared, leaving a less-than-finished mess behind. It was also rife with lossy siblings and things that just plain don't belong with clothing, such as `clothing:brown hair`. \ No newline at end of file +Namespaces not listed above are not "supported" by the janitors and are liable to get siblinged out, removed, and/or mocked if judged being bad and annoying enough to justify the work. Do not take this to mean that all un-listed namespaces are bad, some are created and used by parsers to indicate where an image came from which can be helpful if somebody else wants to fetch the original or check source tags against the PTR tags. But do exercise some care in what you put on the PTR if you use custom namespaces. Recently `clothing:` was removed due to being disliked, no booru using it, and the person(s) pushing for it seeming to have disappeared, leaving a less-than-finished mess behind. It was also rife with lossy siblings and things that just plain don't belong with clothing, such as `clothing:brown hair`. diff --git a/docs/about_docs.md b/docs/about_docs.md index ec8de4a1..f069fd36 100644 --- a/docs/about_docs.md +++ b/docs/about_docs.md @@ -1,34 +1,31 @@ # About These Docs -The Hydrus docs are built with [MkDocs](https://www.mkdocs.org/) using the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. +The Hydrus docs are built with [MkDocs](https://www.mkdocs.org/) using the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. The .md files in the `docs` directory are converted into nice html in the `help` directory. This is done automatically in the built releases, but if you run from source, you will want to build your own. ## Local Setup -To work on the docs locally, [install `mkdocs-material`](https://squidfunk.github.io/mkdocs-material/getting-started/): +To see or work on the docs locally, [install `mkdocs-material`](https://squidfunk.github.io/mkdocs-material/getting-started/): The recommended installation method is `pip`: ``` pip install mkdocs-material ``` +## Building + +To build the help, run: +``` +mkdocs build -d help +``` +In the base hydrus directory (same as the `mkdocs.yml` file), which will build it into the `help` directory. You will then be good! + +Repeat the command and MkDocs will clear out the old directory and update it, so you can fold this into any update script. + ## Live Preview -Once installed you can run the live preview development server with +To edit the `docs` directory, you can run the live preview development server with: ``` mkdocs serve ``` -It will automatically rebuild the site when you save it and reload the page in your browser. - -## Building - -To build the docs site (for example if running from source), run: -``` -mkdocs build -``` -This by default builds the docs into the `site/` directory. To build to the traditional `help/` directory use -``` -mkdocs build -d help -``` - -The docs are automatically deployed to GitHub Pages on every push to the `master` branch. They are also built automatically in the GitHub Actions workflows for each release and included in those builds. \ No newline at end of file +Again in the base hydrus directory. It will host the help site at [http://127.0.0.1:8000/](http://127.0.0.1:8000/), and when you change a file, it will automatically rebuild and reload the page in your browser. diff --git a/docs/changelog.md b/docs/changelog.md index 70f8c65c..7d8051fd 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,4 +1,4 @@ -# Changelog +# changelog !!! note This is the new changelog. For versions prior to 466 see the [old changelog](old_changelog.html). @@ -296,4 +296,4 @@ * fixed some 'broken object load' error handling to print the timestamp of the specific bad object, not whatever timestamp was requested. this error handling now also prints the full dump name and version to the log, and version to the exported filename. I was working with a user who had broken subs this week, and lacking this full info made things just a little trickier to put back together * fixed some drag and drop handling where it was possible to drop thumbnails on a certain location of a page of pages that held an empty page of pages but it would not create a new child media page to hold them * misc serverside db code cleanup -* fixed python 3.10 type bugs in window coordinate saving and Qt image generation from buffer (issue #1027) \ No newline at end of file +* fixed python 3.10 type bugs in window coordinate saving and Qt image generation from buffer (issue #1027) diff --git a/docs/getting_started_installing.md b/docs/getting_started_installing.md index 276438aa..b6bb7f1c 100644 --- a/docs/getting_started_installing.md +++ b/docs/getting_started_installing.md @@ -129,6 +129,8 @@ As a result, if you get a failure on trying to do a big update, try cutting the If you narrow the gap down to just one version and still get an error, please let me know. I am very interested in these sorts of problems and will be happy to help figure out a fix with you (and everyone else who might be affected). +_All that said, and while updating is complex and every client is different, one user recently did a giant multi-year update and found this route worked and was efficient: 204 > 238 > 246 > 291 > 328 > 335 > 376 > 421 > 466 > 474_ + ## backing up !!! danger "I am not joking around: if you end up liking hydrus, you should back up your database" diff --git a/docs/old_changelog.html b/docs/old_changelog.html index 1c3dc927..0929f5bb 100644 --- a/docs/old_changelog.html +++ b/docs/old_changelog.html @@ -635,7 +635,7 @@
  • if you have autocomplete tag search typed, and results from thumbnails displayed, and you flip 'searching immediately' off, the search will now automatically update and give you full database numbers immediately
  • .
  • help:
    • -
  • I moved 'searching with wildcards' from the advanced help to the 'more getting started with files' help here: https://hydrusnetwork.github.io/hydrus/help/getting_started_more_files.html
    • +
  • I moved 'searching with wildcards' from the advanced help to the 'more getting started with files' help here: https://hydrusnetwork.github.io/hydrus/getting_started_more_files.html
  • I also wrote a more detailed description of what the autocomplete dropdown buttons do in that page
  • I also wrote a brief description of how a system:limit query will try to clip according to the current file sort, getting the n 'biggest files' and so on
  • .
    • @@ -754,7 +754,7 @@
  • consolidated and optimised the pre-work checks on all importers/downloaders in pages. pages with idling/finished/paused downloaders will consume just a little less CPU and need to talk to fewer important objects
  • renamed the shortcut sets for viewer/preview media windows and clarified that they are mouse only for now. the new seek command works with these, but you'd have to map ctrl+right-click or something
  • improved the system predicate unit tests to catch datatype problems like with last week's hotfix and system:time imported
    • -
  • advanced archive/delete stuff: wrote up a neat idea I had about using local parents applied to the PTR to make fast multi-tag processing workflows here: https://hydrusnetwork.github.io/hydrus/help/advanced_parents.html#parent_favourites
    • +
  • advanced archive/delete stuff: wrote up a neat idea I had about using local parents applied to the PTR to make fast multi-tag processing workflows here: https://hydrusnetwork.github.io/hydrus/advanced_parents.html#parent_favourites
  • .
  • bug fixes:
  • an important tag search bug is fixed. for some users, files that were imported before a service was added were not appearing in some of that service's search results, or their tag counts were not added in certain tag autocomplete results. this file miscount is fixed, and holes will be filled on database update. it should not take too long to fix, although different users will have different situations
    • @@ -1633,7 +1633,7 @@
  • fixed a bug in the 'add tags before import' dialog for local imports where deleting a 'quick namespace' was not updating the tag list above
  • .
  • windows clean install:
    • -
  • I moved to a new windows dev machine this week and a bunch of libraries were updated. I do not believe the update on Windows _needs_ a clean install this week, as a new dll conflict actually hits the coincidentally now-optional PyOpenSSL, but it is worth doing if you want to start using the Client API soon, and it has been a while, so let's be nice and clean. if you extract the release on Windows, please check out this guide: https://hydrusnetwork.github.io/hydrus/help/getting_started_installing.html#clean_installs
    • +
  • I moved to a new windows dev machine this week and a bunch of libraries were updated. I do not believe the update on Windows _needs_ a clean install this week, as a new dll conflict actually hits the coincidentally now-optional PyOpenSSL, but it is worth doing if you want to start using the Client API soon, and it has been a while, so let's be nice and clean. if you extract the release on Windows, please check out this guide: https://hydrusnetwork.github.io/hydrus/getting_started_installing.html#clean_installs
  • the Windows installer has been updated to remove many old files. it should now do clever clean installs every week, you have nothing to worry about!™
  • .
  • boring db breakup:
    • @@ -1896,7 +1896,7 @@
  • misc cleanup for duplicates page
  • .
  • database modes:
    • -
  • a new 'program launch arguments' help page now talks about all the available command line switches, here: https://hydrusnetwork.github.io/hydrus/help/launch_arguments.html
    • +
  • a new 'program launch arguments' help page now talks about all the available command line switches, here: https://hydrusnetwork.github.io/hydrus/launch_arguments.html
  • added the '--db_journal_mode' launch switch to set the SQLite journal mode. default is WAL, permitted values are also TRUNCATE, PERSIST, and MEMORY
  • ensured --db_synchronous_override was hooked up correctly
  • the old disk cache options under _speed and memory_ are removed, along with various deprecated disk cache load calls and code
    • @@ -8240,7 +8240,7 @@

  • version 245