Merge pull request #15 from AP6YC/14-docs-typos

14 docs typos

.gitignore

@@ -5,6 +5,9 @@
 # Development/scratch folder
 _dev/
 
+# IDE ignores
+.vscode/
+
 # -----------------------------------------------------------------------------
 # JULIA IGNORES
 # -----------------------------------------------------------------------------

README.md

@@ -1,6 +1,4 @@
-# PyCallJLD2.jl
-
-[![pycalljld2-header](docs/src/assets/logo.png)][docs-dev-url]
+[![pycalljld2-header](https://github.com/AP6YC/FileStorage/blob/main/PyCallJLD2/header.png?raw=true)][docs-dev-url]
 
 This package is to [JLD2][jld2] what [PyCallJLD][pycalljld] is to [JLD][jld], implementing a serializer for saving and loading [PyCall][pycall] [`PyObject`][pyobject-readme]s with JLD2.
 
@@ -38,13 +36,12 @@ Please see the official [documentation][docs-dev-url] for usage and contribution
 
 ## Table of Contents
 
-- [PyCallJLD2.jl](#pycalljld2jl)
-  - [Table of Contents](#table-of-contents)
-  - [Usage](#usage)
-  - [Attribution](#attribution)
-    - [Authors](#authors)
-    - [Packages](#packages)
-    - [License](#license)
+- [Table of Contents](#table-of-contents)
+- [Usage](#usage)
+- [Attribution](#attribution)
+  - [Authors](#authors)
+  - [Packages](#packages)
+  - [License](#license)
 
 ## Usage
 

docs/.gitignore

@@ -1,2 +1,9 @@
 build/
 site/
+
+# DemoCards intermediate compilation directories
+src/democards/
+src/examples/
+
+# Downloads folder for files grabbed during docs generation
+src/assets/downloads/

docs/examples/tutorials/config.json

@@ -1,4 +1,4 @@
 {
     "title": "Tutorials",
-    "description": "These examples demonstrate some low-level usage of the Julia programming language and subroutines of the CFAR project itself."
+    "description": "These practical examples demonstrate how to use the `PyCallJLD2.jl` package in various contexts."
 }

docs/make.jl

@@ -53,6 +53,58 @@ if haskey(ENV, "DOCSARGS")
     end
 end
 
+
+# -----------------------------------------------------------------------------
+# DOWNLOAD LARGE ASSETS
+# -----------------------------------------------------------------------------
+
+# Point to the raw FileStorage location on GitHub
+top_url = raw"https://media.githubusercontent.com/media/AP6YC/FileStorage/main/PyCallJLD2/"
+
+# List all of the files that we need to use in the docs
+files = [
+    "header.png",
+]
+
+# Make a destination for the files, accounting for when folder is AdaptiveResonance.jl
+assets_folder = joinpath("src", "assets")
+if basename(pwd()) == PROJECT_NAME || basename(pwd()) == PROJECT_NAME * ".jl"
+    assets_folder = joinpath(DOCS_NAME, assets_folder)
+end
+
+download_folder = joinpath(assets_folder, "downloads")
+mkpath(download_folder)
+download_list = []
+
+# Download the files one at a time
+for file in files
+    # Point to the correct file that we wish to download
+    src_file = top_url * file * "?raw=true"
+    # Point to the correct local destination file to download to
+    dest_file = joinpath(download_folder, file)
+    # Add the file to the list that we will append to assets
+    push!(download_list, dest_file)
+    # If the file isn't already here, download it
+    if !isfile(dest_file)
+        download(src_file, dest_file)
+        @info "Downloaded $dest_file, isfile: $(isfile(dest_file))"
+    else
+        @info "File already exists: $dest_file"
+    end
+end
+
+# Downloads debugging
+detailed_logger = Logging.ConsoleLogger(stdout, Info, show_limited=false)
+with_logger(detailed_logger) do
+    @info "Current working directory is $(pwd())"
+    @info "Assets folder is:" readdir(assets_folder, join=true)
+    # full_download_folder = joinpath(pwd(), "src", "assets", "downloads")
+    @info "Downloads folder exists: $(isdir(download_folder))"
+    if isdir(download_folder)
+        @info "Downloads folder contains:" readdir(download_folder, join=true)
+    end
+end
+
 # -----------------------------------------------------------------------------
 # GENERATE
 # -----------------------------------------------------------------------------

docs/src/index.md

@@ -4,9 +4,7 @@ DocTestSetup = quote
 end
 ```
 
-```@raw html
-<img src="assets/logo.png" width="300">
-```
+![header](assets/downloads/header.png)
 
 # PyCallJLD2.jl
 

docs/src/man/guide.md

@@ -1,5 +1,36 @@
 # [Package Guide](@id package-guide)
 
+To work with the `PyCallJLD2.jl` package, you should know:
+
+- [How to install the package](@ref installation)
+- [How to use the package](@ref basic-usage)
+
+## [Installation](@id installation)
+
+The `PyCallJLD2.jl` package can be installed using the Julia package manager.
+From the Julia REPL, type `]` to enter the Pkg REPL mode and run
+
+```julia-repl
+julia> ]
+(@v1.9) pkg> add PyCallJLD2
+```
+
+Alternatively, it can be added to your environment in a script with
+
+```julia
+using Pkg
+Pkg.add("PyCallJLD2")
+```
+
+If you wish to have the latest changes between releases, you can directly add the GitHub repo at an arbitrary branch (such as `develop`) as a dependency with
+
+```julia-repl
+julia> ]
+(@v1.9) pkg> add https://github.com/AP6YC/PyCallJLD2.jl#develop
+```
+
+## [Basic Usage](@id basic-usage)
+
 To save and load `JLD2`, load `PyCall`, `JLD2`, and `PyCallJLD2` in the same scope as where you intend to use the `JLD2.save` and `JLD2.load` functions.
 If you are coming from `PyCallJLD`, simply replace `JLD` with `JLD2` everywhere in your usage: