horizon-eda / horizon-docs Goto Github PK

@niclashoyer I couldn't quite figure out the package needed to get the libzip headers on opensuse. Is it libzip-devel?

Before investing a lot of time, I thought it would be better to outline a plan for the documentation. The stuff that is there is in parts not too bad, but it lacks a clear structure. This is IMO quite important, because the useres should feel that everything e.g. the Schematic Editor can do is listed in the section Schematic Editor.

I suggest we divide it into these 6 main sections:

1. About

This is the landing page, describes what horizon EDA is, what it is not and links to all the important pages. This is mostly about giving the users honest information so they can decide whether it is something for them or not, so a Feature overview.

2. Getting Started

This is a Quick guide how to get started with the software: Download, Setup, Downloading the official Pool (if necessary), Starting a Project, fundamental interface information (like the spacebar menu and the interactive manipulator). All of this should be kept on a basic level and it should be a quick read, while it could highlight some nice features (those who are interested after reading the About section should feel what is behind the whole thing).

3. Schematic Editor

A more detailed documentation of the schematic editor
Additionally things like:

4. Board Editor

A more detailed documentation of the Board editor
Additionally things like: How to import dxf, exporting step, fabrication output, Copying Layout and Placement, .

5. Pool Manager

A clear definition of the pool and its merits and how thinks work together, including info about parameter programs, padstacks and the like. A "guide" on how to create a package and a part. Link to resources and information for contributers. Suggestions how to organize pools.

6. Advanced Topics

Anything that doesn't really fit in

• Building from Source
• CLI usage
• Maintaining pools with git
• Generating Parts by scripts
• ...

All of this probably demands a different layout for the menu, probably something like this:

I have no idea how to change this on my own, but with a little help I could fill the skeleton up with content and copy existing things over. Maybe making a branch would be a good idea?

On Ubuntu 24.04, it's necessary to install the package libocct-ocaf-dev instead of liboce-ocaf-dev. Might want to add a clause to the build notes to cover that.

Document the outcome of the discussion here:
horizon-eda/horizon#256

horizon-eda/horizon@7406a05

Screenshot from the doc below. I only found that pressing ESC turns hover select on, clicking on a background does not re-enable it (IMO I would not like if it did anyway).

I am trying to build the documentation locally, so I can get a preview of what I am working on. I am just getting familiar with sphinx, so maybe this is my own fault, or some version incompatibility I use:

>>> sphinx.version_info
(1, 6, 7, 'final', 0)

What I tried

• When I run sphinx-build -b html . ../html inside the repo, it complains about a missing conf.py
• When I ignore the conf.py via sphinx-build -C -b html . ../html it complains that there is no contents.rst¹
• I then temporarily added a conf.py with master_doc = 'index' inside, but then he doesn't create the TOC with multiple warnings of the kind: WARNING: document isn't included in any toctree

What I suspect

• I installed sphinx via apt-get python3-sphinx, maybe it is a python3 vs python27 issue?
• Maybe you have a conf.py somewhere that isn't in this repo for some reason

If we sort this out, we might add some info on how to build this documentation locally to the Readme, to make further contribution easier.

¹ this is apparently due to the fact that Sphinx changed this in Changed in version 2.0: The default is changed to 'index' from 'contents'. So I assume you use version 1.something