Merge pull request #530 from nbenaglia/feature/improve_doc_developers

Improve documentation for developers

.gitignore

@@ -2,3 +2,4 @@
 perf.data
 perf.data.old
 flamegraph.svg
+.vscode/

README.md

@@ -1,8 +1,8 @@
 # Gossip
 
-## Gossip is a desktop client for nostr.
+## Gossip is a desktop client for NOSTR
 
-Nostr is an open social media protocol empowering lots of software such as this client. The experience is kind of like Twitter except that you control your own account, and you can post to many different independent places called "relays". People are finding many additional uses for nostr that go far beyond micro-blogging or chatting, but this client is focused on those.
+Nostr is an open social media protocol empowering lots of software such as this client. The experience is kind of like Twitter except that you control your own account, and you can post to many different independent places called "relays". People are finding many additional uses for NOSTR that go far beyond micro-blogging or chatting, but this client is focused on those.
 
 Nostr stands for "Notes and Other Stuff Transmitted by Relays."
 
@@ -92,8 +92,8 @@ The following features make gossip different than most other nostr clients so fa
 If when you pull gossip it doesn't pull cleanly, I may have done a rare force-push. Run these commands to reset your master branch:
 
 ````bash
-$ git fetch
-$ git reset --hard origin/master
+git fetch
+git reset --hard origin/master
 ````
 
 ### Step 1 - Install Rust
@@ -113,25 +113,25 @@ Most dependencies are probably already installed in your base operating system.
 
 #### macOS
 
-a. Install rust with rust-up: https://rustup.rs/
-b. Install homebrew if you don't have it yet https://brew.sh/
+a. Install rust with rust-up: <https://rustup.rs/>
+b. Install homebrew if you don't have it yet <https://brew.sh/>
 c. Install these dependencies:
 
-```
+```bash
 brew install cmake sdl2 pkg-config ffmpeg
 ```
 
 ### Step 3 - Clone this Repository
 
 ````bash
-$ git clone https://github.com/mikedilger/gossip
+git clone https://github.com/mikedilger/gossip
 ````
 
 ### Step 4 - Compile
 
 ````bash
-$ cd gossip
-$ cargo build --release
+cd gossip
+cargo build --release
 ````
 
 The output will be a binary executable in `target/release/gossip`
@@ -141,7 +141,7 @@ This binary should be portable to similar systems with similar hardware and oper
 If you want a binary optimized for your exact processor with the newest CPU features enabled, and all gossip features enabled:
 
 ````bash
-$ RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable" cargo build --features=lang-cjk,video-ffmpeg --release
+RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable" cargo build --features=lang-cjk,video-ffmpeg --release
 ````
 
 Everything gossip needs (fonts, icons) is baked into this executable. It doesn't need to find assets. So you can move it and run it from anywhere.
@@ -149,7 +149,7 @@ Everything gossip needs (fonts, icons) is baked into this executable. It doesn't
 To make the binary smaller,
 
 ````bash
-$ strip gossip
+strip gossip
 ````
 
 ### Step 5 - Do it all again
@@ -157,10 +157,10 @@ $ strip gossip
 The `master` branch changes quickly.  When you want to update, do it all again, something like this:
 
 ````bash
-$ git pull
-$ cargo build --release
-$ strip ./target/release/gossip
-$ ./target/release/gossip
+git pull
+cargo build --release
+strip ./target/release/gossip
+./target/release/gossip
 ````
 
 ## Compile Options
@@ -180,7 +180,6 @@ If you wish to switch to your native TLS provider, use the following compile opt
 
 ### Language Support
 
-
 #### Chinese, Japanese and Korean character sets
 
 Gossip by default does not include the CJK font because it is larger than all other languages put together, and most gossip users don't recognize those characters. If you do recognize such characters, you can compile in that font with:
@@ -207,7 +206,7 @@ Compile with
 
 ### Performance issues
 
-If you are having performance issues, please see [PERFORMANCE.md](PERFORMANCE.md).
+If you are having performance issues, please see [PERFORMANCE.md](docs/PERFORMANCE.md).
 
 ## Technology Involved
 
@@ -221,11 +220,13 @@ If you are having performance issues, please see [PERFORMANCE.md](PERFORMANCE.md
 
 ## License
 
- * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
 
 ### Contribution
 
-All contributions welcome, please check the [development guidelines](DEVELOPING.md) before starting to code.
+All contributions welcome, please check the [development guidelines](docs/DEVELOPING.md) before starting to code.
+
+Please join [Gossip Telegram Channel](https://t.me/gossipclient).
 
 Anyone interested in replacing the GUI with something much better, or keeping it as egui but making it much better, would be greatly appreciated.
 
@@ -233,13 +234,13 @@ Unless you explicitly state otherwise, any contribution intentionally submitted
 
 ## On Nostr
 
-### The official gossip account:
+### The official gossip account
 
 nprofile1qqsrjerj9rhamu30sjnuudk3zxeh3njl852mssqng7z4up9jfj8yupqpzamhxue69uhhyetvv9ujumn0wd68ytnfdenx7tcpz4mhxue69uhkummnw3ezummcw3ezuer9wchszxmhwden5te0dehhxarj9ekkj6m9v35kcem9wghxxmmd9uq3xamnwvaz7tm0venxx6rpd9hzuur4vghsz8nhwden5te0dehhxarj94c82c3wwajkcmr0wfjx2u3wdejhgtcsfx2xk
 
 npub189j8y280mhezlp98ecmdzydn0r8970g4hpqpx3u9tcztynywfczqqr3tg8
 
-### Mike Dilger:
+### Mike Dilger
 
 nprofile1qqswuyd9ml6qcxd92h6pleptfrcqucvvjy39vg4wx7mv9wm8kakyujgpzamhxue69uhhyetvv9ujumn0wd68ytnfdenx7tcprpmhxue69uhkzapwdehhxarjwahhy6mn9e3k7mf0qyt8wumn8ghj7etyv4hzumn0wd68ytnvv9hxgtcprdmhxue69uhkummnw3ezumtfddjkg6tvvajhytnrdakj7qgnwaehxw309ahkvenrdpskjm3wwp6kytcpremhxue69uhkummnw3ez6ur4vgh8wetvd3hhyer9wghxuet59uq32amnwvaz7tmwdaehgu3wdau8gu3wv3jhvtct8l34m
 
@@ -249,4 +250,4 @@ You can also my NIP-05 address of `mike@mikedilger.com` which will also hook you
 
 I'd prefer if you trusted `mike@mikedilger.com` higher than my public key at this point in time since key management is still pretty bad. That is the inverse of the normal recommendation, but my private key has not been treated very carefully as I never intended it to be my long-term keypair (it just became that over time).  Also, I fully intend to rollover my keys once gossip supports the key-rollover NIP, whatever that is (or will be).
 
-You can tip me at my Bitcoin Lighting address: decentbun13@walletofsatoshi.com == lnurl1dp68gurn8ghj7ampd3kx2ar0veekzar0wd5xjtnrdakj7tnhv4kxctttdehhwm30d3h82unvwqhkgetrv4h8gcn4dccnxv563ep
+You can tip me at my Bitcoin Lighting address: <decentbun13@walletofsatoshi.com> == lnurl1dp68gurn8ghj7ampd3kx2ar0veekzar0wd5xjtnrdakj7tnhv4kxctttdehhwm30d3h82unvwqhkgetrv4h8gcn4dccnxv563ep

devrun.sh

@@ -1,4 +0,0 @@
-#!/bin/bash
-
-cargo build --features=lang-cjk,video-ffmpeg && \
-    RUST_BACKTRACE=1 RUST_LOG="info,gossip=debug" ./target/debug/gossip

docs/DEVELOPING.md

@@ -4,18 +4,20 @@ Gossip is architected with the following components:
 
 - A User Interface thread, synchronous
 - Tokio asynchronous runtime running
-    - An overlord (handles most jobs)
-    - A set of minions (each one handles one relay)
+  - An overlord (handles most jobs)
+  - A set of minions (each one handles one relay)
 
 ## Keeping the UI responsive
 
 The most important thing to be aware of is that the User Interface thread repeatedly calculates what to draw and potentially redraws up to 60 frames per second, therefore it **must** not run any slow code.
 
 To that end, the following are allowed from the UI thread:
+
 - Locking global variables (since nearly all locks in gossip are intended to be rapidly released)
 - Sending messages to the overlord.
 
 The following is NOT appreciated when done from the UI thread:
+
 - Database calls, or calls to functions that do database calls
 - Internet queries, or calls to functions that query over the Internet
 
@@ -31,7 +33,8 @@ The overlord generally is the one to send messages to minions using the GLOBALS.
 
 ## Flow
 
-The flow generally happens like this
+The flow generally happens like this:
+
 - The user interacts with the UI
 - The UI requests something of the Overlord
 - The overlord either does it, or spawns a task to do it if it takes too long (the overlord should also remain somewhat responsive).
@@ -45,16 +48,16 @@ The flow generally happens like this
 
 ## Pull Requests
 
-I prefer that you run and make pass
+I prefer that you run and make pass:
 
-````sh
-$ cargo clippy
+````bash
+cargo clippy
 ````
 
 and then
 
-````sh
-$ cargo fmt
+````bash
+cargo fmt
 ````
 
 before you issue a pull request. Otherwise I'll have to do it for you.

docs/DOCUMENTATION.md

@@ -0,0 +1,15 @@
+# DOCUMENTATION
+
+You may want to generate the Gossip Rust Documentation from root folder:
+
+````bash
+cargo doc --lib
+````
+
+The output in `target/doc/gossip_lib/index.html` may be browsed.
+
+For lasiest people the following will directly open the browser:
+
+````bash
+cargo doc --lib --open
+````

docs/PERFORMANCE.md

@@ -41,7 +41,7 @@ This issue will be ameliorated somewhat in the future when you can have differen
 Gossip should be compiled in release mode. You can also compile it for your individual processor to squeeze out the most performance (the following line leaves out feature flags, you'll wnat to determine which ones are right for you):
 
 ````bash
-$ RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable" cargo build --release
+RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable" cargo build --release
 ````
 
 ### Dumb Programmers

filescontaining.sh

@@ -1,4 +0,0 @@
-#!/bin/bash
-
-find . -name .git -prune -o -name target -prune -o -type f -exec grep -H "$1" {} \; \
-     | awk -F: '{print $1}' | uniq

find.sh

@@ -1,3 +0,0 @@
-#!/bin/bash
-
-find . -name .git -prune -o -name target -prune -o -type f -exec grep -H "$1" {} \;

findfile.sh

@@ -1,4 +0,0 @@
-#!/bin/bash
-
-find . -name .git -prune -o -name target -prune -o -name "$1" -print
-

gossip-bin/src/ui/mod.rs

@@ -56,7 +56,7 @@ use self::widgets::NavItem;
 use self::wizard::{WizardPage, WizardState};
 
 pub fn run() -> Result<(), Error> {
-    let icon_bytes = include_bytes!("../../../gossip.png");
+    let icon_bytes = include_bytes!("../../../logo/gossip.png");
     let icon = image::load_from_memory(icon_bytes)?.to_rgba8();
     let (icon_width, icon_height) = icon.dimensions();
 
@@ -481,7 +481,7 @@ impl GossipUi {
         submenu_ids.insert(SubMenu::Help, egui::Id::new(SubMenu::Help.to_id_str()));
 
         let icon_texture_handle = {
-            let bytes = include_bytes!("../../../gossip.png");
+            let bytes = include_bytes!("../../../logo/gossip.png");
             let image = image::load_from_memory(bytes).unwrap();
             let size = [image.width() as _, image.height() as _];
             let image_buffer = image.to_rgba8();

packaging/RELEASE.md

@@ -1,3 +1,4 @@
+# RELEASE
 
 0. DON'T update dependencies. DON'T 'cargo update'.  Do that kind of stuff right after
    releasing. Because that stuff presents risk.
@@ -9,9 +10,11 @@
 
 2. Stabilize the code. Make all these happy:
 
-   $ cargo clippy
-   $ cargo fmt
-   $ cargo test
+   ````bash
+      cargo clippy
+      cargo fmt
+      cargo test
+   ````
 
 3. Edit Cargo.toml and change the version (remove the -unstable).
    Compile so you get a new Cargo.lock
@@ -28,24 +31,33 @@
 
 5. Build the debian:
 
-   $ cd debian
-   $ ./deb.sh
+   ````bash
+      cd debian
+      ./deb.sh
+   ````
 
-6. Build the appimage
+6. Build the appimage:
 
-   $ cd appimage
-   $ cargo appimage --features="lang-cjk,video-ffmpeg"
+   ````bash
+      cd appimage
+      cargo appimage --features="lang-cjk,video-ffmpeg"
+   ````
 
-7. Build the windows
+7. Build the windows:
 
-   $ cd windows
-   Follow the windows/README.txt
+   ````bash
+      cd windows
+   ````
 
-8. Build the macos
+   and follow the [Windows README](windows/README.md)
 
-   $ cd macos
-   $ ./build_macos.sh
-   $ ./build_macos_intel.sh
+8. Build the macos:
+
+   ````bash
+      cd macos
+      ./build_macos.sh
+      ./build_macos_intel.sh
+   ````
 
 9. Bundle the files, create SHA256 hashes
 
@@ -55,10 +67,8 @@
 
 12. Announce release on nostr under gossip account
 
-
 -----------------
 
-
 This is a draft of the steps taken to make a release.
 I intend to flesh this out as I actually make releases.
 
@@ -77,10 +87,9 @@ gossip
 ├── nostr-types
 └── qrcode
 
-
 Try to push our dependency changes upstream:
-  https://github.com/mikedilger/qrcode-rust  (unlikely, stale for >3 years)
-  https://github.com/mikedilger/egui
+  <https://github.com/mikedilger/qrcode-rust>  (unlikely, stale for >3 years)
+  <https://github.com/mikedilger/egui>
 
 nostr-types
    -- cargo update, and check for new versions, maybe update dependencies
@@ -118,19 +127,23 @@ gossip
    -- master
       -- version 0.N+1.0-unstable
 
------------------------------
+-----------------
+
 Package & Publish of gossip:
 
 Package for windows:
- * main version, as .msi
- * main version with lang-cjk, as .msi
+
+* main version, as .msi
+* main version with lang-cjk, as .msi
 
 Package for debian:
- * main version, as .msi
- * main version with lang-cjk, as .msi
+
+* main version, as .msi
+* main version with lang-cjk, as .msi
 
 Create github release (it will create source tar files)
- * Post the windows .msi files
- * Post the debian .deb files
+
+* Post the windows .msi files
+* Post the debian .deb files
 
 Update aur.archlinux.org PKGBUILD

packaging/macos/build_macos.sh

@@ -39,7 +39,7 @@ cp macos_launch.sh $APP_DIR/Contents/MacOS/$APP_NAME
 echo "Copying Icon"
 mkdir -p $APP_DIR/Contents/Resources
 cat Info.plist | sed s/__VERSION__/$VERSION/g > $APP_DIR/Contents/Info.plist
-cp ../../$NAME.png ../../$NAME.svg $APP_DIR/Contents/Resources
+cp ../../logo/$NAME.png ../../logo/$NAME.svg $APP_DIR/Contents/Resources
 
 echo "Creating dmg"
 mkdir -p $APP_NAME

packaging/macos/build_macos_intel.sh

@@ -39,7 +39,7 @@ cp macos_launch.sh $APP_DIR/Contents/MacOS/$APP_NAME
 echo "Copying Icon"
 mkdir -p $APP_DIR/Contents/Resources
 cat Info.plist | sed s/__VERSION__/$VERSION/g > $APP_DIR/Contents/Info.plist
-cp ../../$NAME.png ../../$NAME.svg $APP_DIR/Contents/Resources
+cp ../../logo/$NAME.png ../../logo/$NAME.svg $APP_DIR/Contents/Resources
 
 echo "Creating dmg"
 mkdir -p $APP_NAME

packaging/windows/README.md

@@ -0,0 +1,52 @@
+# WINDOWS
+
+Prerequisite for packaging:
+
+* You need Wix 4 tools installed, probably with DOTNET installed first.
+
+Compile:
+
+````dos
+  rustup update
+  cargo build --features=lang-cjk --release
+````
+
+Copy the binary to the packaging diretory
+
+````dos
+  cp ..\..\target\release\gossip.exe .
+````
+
+Copy the gossip.png here
+
+````dos
+  cp ..\..\logo\gossip.png .
+````
+
+For new versions of gossip, update `gossip.wxs`:
+
+* UPDATE the Package.Version, SummaryInformation.Description
+* UPDATE the Package.ProductCode GUID to a new one
+* KEEP the UpgradeCode GUID (it should never change, it ties different versions together)
+* Change a component GUID ONLY IF the absolute path changes.
+
+Packaging:
+
+````dos
+  wix build gossip.VERSION.wxs
+````
+
+Upload to github releases.
+
+----
+To install the package, either double-click the MSI, or
+
+````dos
+  msiexec gossip.msi
+````
+
+To remove the package from your windows computer:
+
+````dos
+  msiexec /x gossip.msi
+````

packaging/windows/README.txt

@@ -1,39 +0,0 @@
-
-Prerequisite for packaging:
-
-* You need Wix 4 tools installed, probably with DOTNET installed first.
-
-Compile:
-
-  $ rustup update
-  $ cargo build --features=lang-cjk --release
-
-Copy the binary to the packaging diretory
-
-  $ cp ..\..\target\release\gossip.exe .
-
-Copy the gossip.png here
-
-  $ cp ..\..\gossip.png .
-
-For new versions of gossip, update gossip.wxs
-    * UPDATE the Package.Version, SummaryInformation.Description
-	* UPDATE the Package.ProductCode GUID to a new one
-    * KEEP the UpgradeCode GUID (it should never change, it ties different versions together)
-    * Change a component GUID ONLY IF the absolute path changes.
-
-Packaging:
-
-  $ wix build gossip.VERSION.wxs
-
-Upload to github releases.
-
-
-----
-To install the package, either double-click the MSI, or
-
-  $ msiexec gossip.msi
-
-To remove the package from your windows computer:
-
-  $ msiexec /x gossip.msi