sphinx-autobuild builds the documentation, serves it on a localhost web
server, automatically rebuilds it when changes are detected, and also
refreshes the web page automatically. With this setup documentation
writers can have the documentation open in their browser, change
documentation source code, and see the updated documentation as soon as
they save the source file, without any other action needed. Beautiful!

Add the tox setup for this, and document it as the preferred way of
working on documentation. The more manual way remains in place for now.

No functional change intended.

Strings in YAML don't have to be quoted in most cases, but must be quote
in some cases. The exact rules are a mess, as highlighted by the
discussion at
https://stackoverflow.com/questions/19109912/yaml-do-i-need-quotes-for-strings-in-yaml.
In FuseSoC's case, quotes are at least required when using negated
CAPI2 expressions, which start with "!" and need quoting.

Instead of confusing our users, the guide now goes with the simplest
possible rule: always quote strings. We limit the quoting to strings
used as value (not as dictionary keys), since keys are always valid
identifiers in our case.

This commit doesn't universally change all our (example) code to use
quotes, but it's a start at least.

Both single and double quotes would work for our use case. To align with
more common use in normal English, as well as with C-based languages and
many others, we prefer double quotes over single ones. Ultimately, the
differences don't matter much for our use case and it's down to
preferences.

The recommended way of building the documentation locally is through
tox. Avoid installing Sphinx for "manual" development environments, tox
already takes care of that.

Add tox as development dependency (it was missing before), and remove
the manual installation of Sphinx.

For now we keep pytest as separate dependency, even though that's not
needed when running tests through tox.

This commit add basic Integer class to support Integer type parameters
for backends defined in edalize. For example: jobs parameter of Vivado.
Please see Issue #515 #515

Up until now, generators have been run from cache_root/generated/<vlnv>.
This is a problem when several builds are run at the same time. Normally, there
should be no need for the intermediate files created by the generator so with
this change we treat them as volatile. If a generated wants to cache the
output it will need to do this internally instead.

be no need for the generated

Several functions were created before the EDAM format was invented
and used names like eda_api to describe the EDAM objects. This makes it
clearer when EDAM objects are being referred to

 - copyto now supports copying directories to the workspace. This is useful
   for copying directories such as Xilinx board files for Vivado.

This argument doesn't have any effect, so there's no need to construct
it. This commit removes the argument from the function and all
call-sites.

It also removes debug messages from in core.get_generators(). The
first wasn't massively helpful (printing flags that had no effect),
and the interesting call site in Edalizer.extract_generators() already
has a log message which was more helpful because it could also print
the core name.

The commit moves the second debug message (per generator found) up to
Edalizer.extract_generators, where it was also duplicated.

There should be no functional change, except to debug messages.

get_work_root and get_tool were originally added as API functions
to bridge some conceptual differences between CAPI1 and CAPI2.
With CAPI1 removed these can be removed as well in favor of the
get_flags functions, since the former are  not very useful API functions

Python 3.11 is in alpha now, but having it in CI helps us be prepared.
CI will always pick up the latest 3.11 version as it moves from alpha to
beta to release ultimately.

These two commands have been deprecated for a while, remove them while
still showing a message to our users informing them what to do instead.

No functional change intended.

This section in tox.ini is unused, but looks like it would need updating
for newer Python versions added to CI. There has not been much upstream
movement on this issue, it's unlikely we'll ever get the behavior we
hoped for.

 - there are two locations in the codebase where file copying takes place depending
   on whether you run fusesoc with the --no-export switch.

Avoid removing the full (tox-created) HOME directory, as it may contain
Python venv components that we are unable to delete at times.

Fixes #546

This didn't matter until 0469da4 because all the 'core_root' paths
were the same. But generated cores now appear in different directories
from one another so we have to get it right.

Packages can now provide more than one package: they provide itself (as
described by the package `name`), and a list of further (virtual)
packages, described by the `virtual` key in the root of the CAPI2 file.

Example:
```
CAPI=2:
name: ::impl2:0
virtual:
  - ::someinterface:0
```

This core provides a core named `::impl2:0` and a core named
`someinterface:0`. Other cores can now depend either `::impl2:0` or
`::someinterface` and always get the `::impl2:0` core.

The keyword `virtual` was chosen over alternatives, such as `provide` to
be distinct from other keywords we use in CAPI2 currently, especially to
be distinct from the concept of providers.

Fixes #235

Commit 6b04028 introduced new code
which broke a test. Fix that. (There was a mid-air collision of two
changes.)

Pytest 8 will deprecate `pytest.warns(None)`. Replace it with an
alternative.

…folder; Updated black version due to bug with older one

* Remove generators temporary directories
* Keep track of generated cores

It seems that previous versions don't work with the latest version of
the "click" library on which they depend.

See https://stackoverflow.com/questions/71673404.

That's the default behaviour of black (which we use). If you use an
editor with flake8 integration, this gets rid of all the wiggly red
lines!

Before this change, you could create a Config object by passing a path
or a file handle (or passing nothing, in which case it loaded up a set
of default paths).

This change removes the file handle option, slightly simplifying the
code.

There's a bit of resulting churn in test_libraries.py, but the result
should be a bit cleaner than what it was (using tempfile's context
managers to avoid leaving stray temporary files and directories
around).

Unused import and unused variable.

There should be no functional change, but one nice property of the new
code is that we no longer use setattr() to set fields (making it much
easier to grep for where e.g. self.build_root gets set).

Note that the helper functions (e.g. _get_build_root) could actually
be static methods at the moment, but the next commit will add a
dependency on self._path, so I left them non-static to avoid churn
there.

This works essentially the same as adding a FUSESOC_IGNORE file to a
directory, but is handy because it can be done (and checked in) before
the directory actually exists.

fixes: #577

No-single-branch flag ensures shallow-clone depth constraint does not make older tags invisible

Co-authored-by: Philipp Wagner <[email protected]>
Co-authored-by: Per Lenander <[email protected]>