Skip to content

Conversation

Tuna2222
Copy link
Contributor

@Tuna2222 Tuna2222 commented Oct 1, 2025

Description

Docs:

  • Add the "Tutorials" section. The "Tutorials" section is designed to show users how to use RLinearAlgebra.jl to solve typical linear algebra problems.
    • Add tutorials/introduction.md
    • Add a least squares example to the tutorials/getting_started.md.
  • Add "checklist.md" subsection to the dev docs.
    • Add checklist for Compressors and Loggers in dev/checklists
  • Add 3 subsections to dev docs contributing.md, design.md, and style_guide.md.
  • Add custom_html.css to format the HTML block in the documents.

Fix: Some spellings and CI's inconsistencies.

Motivation and Context

Refer to the JuMP.jl Tutorials section.

How has this been tested

First, download the RLinearAlgebra.jl to your local Julia environment.
Then, open Julia in the folder of RLinearAlgebra.jl, and use the following codes to see the document:

] activate docs/
using LiveServer
servedocs()

Types of changes

  • CI
  • Docs
  • Feature
  • Fix
  • Performance
  • Refactor
  • Style
  • Test
  • Other (use sparingly):

Checklists:

Code and Comments
If this PR includes modification to the code base, please select all that apply.

  • My code follows the code style of this project.
  • I have updated all package dependencies (if any).
  • I have included all relevant files to realize the functionality of the PR.
  • I have exported relevant functionality (if any).

API Documentation

  • For every exported function (if any), I have included a detailed docstring.
  • I have checked the spelling and grammar of all docstring updates through an external tool.
  • I have checked that the docstring's function signature is correctly formatted and has all arguments.
  • I have checked that the docstring's list of arguments, fields, or return values match the function.
  • I have compiled the docs locally and read through all docstring updates to check for errors.

Manual Documentation

  • I have checked the spelling and grammar of all manual updates through an external tool.
  • Any code included in the docstring is tested using doc tests to ensure consistency.
  • I have compiled the docs locally and read through all manual updates to check for errors.

Testing

  • I have added unit tests to cover my changes. (For Macros, be sure to check
    @code_lowered and
    @code_typed)
  • All new and existing tests passed.
  • I have achieved sufficient code coverage.

@Tuna2222 Tuna2222 self-assigned this Oct 1, 2025
@Tuna2222 Tuna2222 added the documentation Improvements or additions to documentation label Oct 1, 2025
Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds a "Tutorials" section to the documentation, specifically including a least squares example that demonstrates how to use the RLinearAlgebra.jl package's SparseSign compression method. The purpose is to provide hands-on examples for new users to quickly understand the package usage.

  • Adds a complete tutorials framework with introduction and getting started guides
  • Creates a comprehensive least squares solving example using SparseSign compression
  • Adds development documentation including style guides, contributing guidelines, and checklists

Reviewed Changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 6 comments.

Show a summary per file
File Description
src/Compressors/sparse_sign.jl Fixes typo in documentation comment
readme.md Comments out Aqua QA badge
docs/src/tutorials/ Adds new tutorial section with introduction and getting started guide
docs/src/manual/introduction.md Adds comprehensive manual introduction to randomized linear algebra
docs/src/dev/ Adds development documentation including style guide, design docs, and contributing checklists
docs/make.jl Updates documentation structure and deployment configuration
.github/workflows/ Adds new CI/CD workflows for automated version management and documentation

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

Copy link

codecov bot commented Oct 1, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Tuna2222 and others added 5 commits October 8, 2025 09:08
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
@numlinalg numlinalg deleted a comment from Copilot AI Oct 8, 2025
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
@numlinalg numlinalg deleted a comment from Copilot AI Oct 8, 2025
@Tuna2222 Tuna2222 marked this pull request as ready for review October 8, 2025 14:42
Copy link
Contributor

@vp314 vp314 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think removing Dev Docs from this PR and splitting up the tutorials into increasingly more customized pieces would be a better approach.

# Introduction

The purpose of these tutorials is to use examples help
new users quickly get hands on the usage of `RLinearAlgebra.jl`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
new users quickly get hands on the usage of `RLinearAlgebra.jl`.
new users quickly get hands experience using `RLinearAlgebra.jl`.

## How tutorials are structured

Problem sets:
- Least squre problem, solving $$\min_{x} \|Ax - b\|_2^2$$
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Least squre problem, solving $$\min_{x} \|Ax - b\|_2^2$$
- Least squares problem, solving $$\min_{x} \|Ax - b\|_2^2$$

deploydocs(
repo = "github.com/numlinalg/RLinearAlgebra.jl"
repo = "github.com/numlinalg/RLinearAlgebra.jl",
devbranch = "master", # master's newest commit will become dev
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be "main"

"Home" => "index.md",
"Tutorials" => [
"Introduction" => "tutorials/introduction.md",
"Least square" => "tutorials/least_square.md"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"Least square" => "tutorials/least_square.md"
"Least squares" => "tutorials/least_square.md"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change filename to "least_squares.md"

Comment on lines +4 to +6

$$\min_{x} \|Ax - b\|_2^2$$

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we are looking at a consistent linear system in this example, I think we should not present the least squares formulation.

Comment on lines +15 to +19

* **Matrix `A`**: A random $1000 \times 20$ matrix.
* **Vector `b`**: Calculated as $b = A x_{\text{true}}$, with dimensions $1000 \times 1$.
* **Goal**: Find a solution $x$ that is as close as possible to $x_{\text{true}}$.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would remove this. The previous sentence explains things well.


```@example SparseSignExample
# Import relevant libraries
using RLinearAlgebra, Random, LinearAlgebra
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you do not need Random

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Be sure to respect the 92 character limit even in markdown files.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe split up the tutorials into pieces

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants