Larger reorg and simplification of the sidebar

docs/faq.rst

@@ -298,6 +298,83 @@ Using some CI service, why is the version `unknown` or `my_project-0.0.post0.dev
     i.e. ``git fetch origin --tags``.
 
 
+.. _conda-packages:
+
+Creating and distributing `conda` packages
+------------------------------------------
+
+conda_ is an open-source package manager very popular in the Python
+ecosystem that can be used as an alternative to pip_. It is especially helpful
+when distributing packages that rely on compiled libraries (e.g. when you need
+to use some C code to achieve performance improvements) and uses Anaconda_ as
+its standard repository (the PyPI_ equivalent in the conda_ world).
+
+The process of creating conda_ packages consists basically in creating some extra
+files that describe general recipe to build your project in different operating systems.
+These recipe files can in theory coexist within the same repository as generated
+by PyScaffold.
+
+While this approach is completely fine and works well, a package
+uploaded by a regular user to Anaconda_ will not be available if someone simply try to
+install it via ``conda install <pkg name>``.
+This happens because Anaconda_ and conda_ are organised in terms of `channels`_ and regular
+users cannot upload packages to the default channel.
+Instead, separated personal channels need to be used for the upload and explicitly
+selected with the ``-c <channel name>`` option in ``conda install``.
+
+It is important however to consider that mixing many channels together might
+create clashes in dependencies (although conda_ tries very hard to avoid clashes by
+using channel preference ordering and a clever resolution algorithm).
+
+A general practice that emerged in the conda_ ecosystem is to organise packages
+in large communities that share a single and open repository in Anaconda_, that
+rely on specific procedures and heavy continuous integration for publishing
+cohesive packages. These procedures, however, might involve creating a second
+repository (separated from the main code base) to just host the recipe files.
+For that reason, PyScaffold does not currently generate conda_ recipe files
+when creating new projects.
+
+Instead, if you are an open-source developer and are interested in distributing
+packages via conda_, our recommendation is to try `publishing your package on conda-forge`_
+(unless you want to target a specific community such as bioconda_).
+conda-forge_ is one of the largest channels in Anaconda_ and works as the
+central hub for the Python developers in the conda_ ecosystem.
+
+Once you have your package published to PyPI_ using the project generated by PyScaffold,
+you can create a *conda-forge feedstock* [#conda1]_ using a special tool called grayskull_ and
+following the instructions_.
+Please make sure to check PyScaffold community tips in :discussion:`422`.
+
+If you still need to use a personal custom channel in Anaconda_, please
+checkout `conda-build tutorials`_ for further information.
+
+.. tip::
+   It is not strictly necessary to publish your package to Anaconda_ for your
+   users to be able to install it if they are using conda_ --
+   ``pip install`` can still be used from a `conda environment`_.
+   However, if you have dependencies that are also published in Anaconda_ and
+   are not pure Python projects (e.g. ``numpy`` or ``matplotlib``), or that
+   rely on `virtual environments`_, it is generally advisable to do so.
+
+
+.. [#conda1] **feedstock** is the term used by conda-forge_ for the companion
+   repository with recipe files
+
+
+.. _pip: https://pip.pypa.io/
+.. _PyPI: https://pypi.org/
+.. _conda: https://conda.io
+.. _Anaconda: https://anaconda.org
+.. _channels: https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html
+.. _custom channels: https://conda.io/projects/conda/en/latest/user-guide/tasks/create-custom-channels.html
+.. _conda-forge: https://conda-forge.org
+.. _bioconda: https://bioconda.github.io
+.. _publishing your package on conda-forge: https://conda-forge.org/docs/maintainer/adding_pkgs.html
+.. _grayskull: https://pypi.org/project/grayskull/
+.. _instructions: https://conda-forge.org/docs/maintainer/adding_pkgs.html#step-by-step-instructions
+.. _conda-build tutorials: https://docs.conda.io/projects/conda-build/en/latest/user-guide/tutorials/index.html
+.. _conda environment: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#using-pip-in-an-environment
+.. _virtual environments: https://realpython.com/python-virtual-environments-a-primer/
 .. _blog post by Ionel: https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure
 .. _src layout: https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure
 .. _discussions: https://github.com/pyscaffold/pyscaffold/discussions
@@ -325,7 +402,6 @@ Using some CI service, why is the version `unknown` or `my_project-0.0.post0.dev
 .. _pyscaffoldext-dsproject: https://github.com/pyscaffold/pyscaffoldext-dsproject
 .. _Semantic Versioning: https://semver.org/
 .. _dependency hell: https://en.wikipedia.org/wiki/Dependency_hell
-.. _PyPI: https://pypi.org/
 .. _devpi: https://devpi.net/
 .. _Nexus: https://www.sonatype.com/product-nexus-repository
 .. _packaging, versioning and continuous integration: https://florianwilhelm.info/2018/01/ds_in_prod_packaging_ci/