Skip to content

[JOSS revision] Improve INSTALL.md and documentation#673

Open
cvanaret wants to merge 41 commits into
mainfrom
joss_revisions
Open

[JOSS revision] Improve INSTALL.md and documentation#673
cvanaret wants to merge 41 commits into
mainfrom
joss_revisions

Conversation

@cvanaret
Copy link
Copy Markdown
Owner

@cvanaret cvanaret commented Apr 23, 2026

Revision based on openjournals/joss-reviews#10229 (comment)

Major action points:

  • Installation. I'd be nice to have more streamlined installation options. I'd move the precompiled/executable instructions to the top of INSTALL.md. I'd also streamline the use of unopy for Python users.
  • Documentation. Currently, installation instructions, instructions on using the different interfaces, case-studies/examples and theory are scattered across multiple *.md files cited in the main README.md in the project's root folder as well as in https://unosolver.readthedocs.io/en/latest/. I'd recommend unifying all of this information in a single readthedocs webpage. This will centralize installation instructions, theory, examples and so on. You already have everything here, it's just about reorganizing information. I've found a bit confusing to navigate throughout several *.md files and the page to understand all aspects of Uno.
  • OS specific instructions. The "Precompiled libraries and executables" section on INSTALL.md gives somewhat generic/somewhat linux-ish instructions. I'd recommend having OS-specific sections and move this to the top of this page (per comment 1 above).

Minor action points:

  • While restructuring your documentation, I have a minor suggestion: Having a section quickly showing uno through the interfaces. Something like a "Getting Started" or "Usage". One example can be seen here.. Maybe showing unopy + other interfaces in action. I was able to run example_hs015.py successfully. Maybe this is a good candidate?

@cvanaret cvanaret self-assigned this Apr 23, 2026
@cvanaret cvanaret added documentation Improvements or additions to documentation build labels Apr 23, 2026
@cvanaret cvanaret force-pushed the joss_revisions branch 6 times, most recently from b0f1671 to 0d0ffb7 Compare May 1, 2026 08:28
@cvanaret
Copy link
Copy Markdown
Owner Author

cvanaret commented May 5, 2026

@amontoison can you have a look at:

  • the result in the joss_revisions branch
  • the doc

when you have a moment?

I created symlinks from the READMEs to docs/interfaces for C, Fortran and AMPL. Julia and Python have their own READMEs and doc pages.

I need to refine the "Getting started" page before merging.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

build documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants