e3fee2cf46
Prior to this commit, the Odoo documentation was mainly split between
two repositories: odoo/odoo/doc and odoo/documentation-user. Some bits
of documentation were also hosted elsewhere (e.g., wiki, upgrade, ...).
This was causing several problems among which:
- The theme, config, Makefile, and similar technical resources had to
be duplicated. This resulted in inconsistent layout, features, and
build environments from one documentation to another.
- Some pages did not fit either documentation as they were relevant
for both users and developers. Some were relevant to neither of the
two (e.g., DB management).
- Cross-doc references had to be absolute links and they broke often.
- Merging large image files in the developer documentation would bloat
the odoo/odoo repository. Some contributions had to be lightened to
avoid merging too many images (e.g., Odoo development tutorials).
- Long-time contributors to the user documentation were chilly about
going through the merging process of the developer documentation
because of the runbot, mergebot, `odoo-dev` repository, etc.
- Some contributors would look for the developer documentation in the
`odoo/documentation-user` repository.
- Community issues about the user documentation were submitted on the
`odoo/odoo` repository and vice-versa.
Merging all documentations in one repository will allow us to have one
place, one theme, one work process, and one set of tools (build
environment, ...) for all of the Odoo docs.
As this is a good opportunity to revamp the layout of the documentation,
a brand new theme replaces the old one. It features a new way to
navigate the documentation, centered on the idea of always letting the
reader know what is the context (enclosing section, child pages, page
structure ...) of the page they are reading. The previous theme would
quickly confuse readers as they navigated the documentation and followed
cross-application links.
The chance is also taken to get rid of all the technical dangling parts,
performance issues, and left-overs. Except for some page-specific JS
scripts, the Odoo theme Sphinx extension is re-written from scratch
based on the latest Sphinx release to benefit from the improvements and
ease future contributions.
task-2351938
task-2352371
task-2205684
task-2352544
Closes #945
112 lines
4.3 KiB
ReStructuredText
112 lines
4.3 KiB
ReStructuredText
|
|
.. _odoosh-advanced-submodules:
|
|
|
|
==================================
|
|
Submodules
|
|
==================================
|
|
|
|
Overview
|
|
========
|
|
|
|
A `Git submodule <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ allows you to integrate other Git projects
|
|
into your code, without the need to copy-paste all their code.
|
|
|
|
Indeed, your custom modules can depend on modules from other repositories.
|
|
Regarding Odoo, this feature allows you to add modules from other Git repositories into the branches of your repository.
|
|
Adding these dependencies in your branch through submodules makes the deployment of your code and servers easier,
|
|
as you can clone the repositories added as submodules at the same time you clone your own repository.
|
|
|
|
Besides, you can choose the branch of the repository added as submodule
|
|
and you have the control of the revision you want.
|
|
It's up to you to decide whether you want to pin the submodule to a specific revision and when you want to update
|
|
to a newer revision.
|
|
|
|
In Odoo.sh, the submodules give you the possibility to use and depend on modules available in other repositories.
|
|
The platform will detect that you added modules through submodules in your branches
|
|
and add them to your addons path automatically so you can install them in your databases.
|
|
|
|
If you add private repositories as submodules in your branches,
|
|
you need to configure a deploy key in your Odoo.sh project settings and in your repository settings.
|
|
Otherwise Odoo.sh won't be allowed to download them.
|
|
The procedure is detailed in the chapter :ref:`Settings > Submodules <odoosh-gettingstarted-settings-submodules>`.
|
|
|
|
Adding a submodule
|
|
==================
|
|
|
|
With Odoo.sh (simple)
|
|
---------------------
|
|
|
|
.. warning::
|
|
For now it is not possible to add **private** repositories with this method. You can nevertheless
|
|
do so :ref:`with Git <odoosh-advanced-submodules-withgit>`.
|
|
|
|
On Odoo.sh, in the branches view of your project, choose the branch in which you want to add a submodule.
|
|
|
|
In the upper right corner, click on the *Submodule* button, and then on *Run*.
|
|
|
|
.. image:: ./media/advanced-submodules-button.png
|
|
:align: center
|
|
|
|
A dialog with a form is shown. Fill the inputs as follows:
|
|
|
|
* Repository URL: The SSH URL of the repository.
|
|
* Branch: The branch you want to use.
|
|
* Path: The folder in which you want to add this submodule in your branch.
|
|
|
|
.. image:: ./media/advanced-submodules-dialog.png
|
|
:align: center
|
|
|
|
On Github, you can get the repository URL with the *Clone or download* button of the repository. Make sure to *use SSH*.
|
|
|
|
.. image:: ./media/advanced-submodules-github-sshurl.png
|
|
:align: center
|
|
|
|
.. _odoosh-advanced-submodules-withgit:
|
|
|
|
With Git (advanced)
|
|
---------------------
|
|
|
|
In a terminal, in the folder where your Git repository is cloned,
|
|
checkout the branch in which you want to add a submodule:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ git checkout <branch>
|
|
|
|
Then, add the submodule using the command below:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ git submodule add -b <branch> <git@yourprovider.com>:<username/repository.git> <path>
|
|
|
|
Replace
|
|
|
|
* *<git@yourprovider.com>:<username/repository.git>* by the SSH URL of the repository you want to add as submodule,
|
|
* *<branch>* by the branch you want to use in the above repository,
|
|
* *<path>* by the folder in which you want to add this submodule.
|
|
|
|
Commit and push your changes:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ git commit -a && git push -u <remote> <branch>
|
|
|
|
Replace
|
|
|
|
* <remote> by the repository on which you want to push your changes. For a standard Git setup, this is *origin*.
|
|
* <branch> by the branch on which you want to push your changes.
|
|
Most likely the branch you used :code:`git checkout` on in the first step.
|
|
|
|
You can read the `git-scm.com documentation <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_
|
|
for more details about the Git submodules.
|
|
For instance, if you would like to update your submodules to have their latest revision,
|
|
you can follow the chapter
|
|
`Pulling in Upstream changes <https://git-scm.com/book/en/v2/Git-Tools-Submodules#_pulling_in_upstream_changes>`_.
|
|
|
|
Ignore modules
|
|
==============
|
|
|
|
If you're adding a repository that contains a lot of modules, you may want to ignore some of them in case there are any
|
|
that are installed automatically. To do so, you can prefix your submodule folder with a :code:`.`. The platform will
|
|
ignore this folder and you can hand pick your modules by creating symlinks to them from another folder.
|