[docs] acumulating information for bob package development from other packages
In this merge request all the information about local development of bob packages will be added and updated. These information have been in the documentation of bob.buildout and bob.extension before.
Merge request reports
Activity
@zmostaani: are you aware this pipeline failed?
@andre.anjos I am aware that it is failing but there is still a lot to be done here so I did not look into it. Does it affect the nightlies in anyway or interfere with other's work?
added 1 commit
- b3284847 - [docs] more modification to include all the information about building new...
added 1 commit
- 87aaf69d - [docs] more modifs to include four different way of developing packages
@amohammadi @andre.anjos I prepared the first draft for developing bob packages. It is not clean but I would appreciate if you could give me your feedback about the structure.
This is how it goes:
- TLDR: This explains how to build a new package from scratch and develop existing package along side it, only with codes. Basically the most complicated one.
- Local development of existing bob packages: It contains two cases. Just to develop one package, or develop two existing packages while one is dependent on the other.
- Creating new bob package: This also includes two cases. First, to create one empty package and start using it. Second, to create a new package from scratch and also develop two existing bob packages in the same project.
- At the end there are some details about buildout and mr.developer. I may decide to move them all to the next section "Additional consideration".
The next section "Additional consideration" at the time is just a copy of previous info on bob.extension and new info on bob.devtools without any modification. There are redundant and some old information which will be cleaned afterwards.
- doc/development.rst 0 → 100644
1 .. _bob.extension.development: 2 3 ========================================= 4 Local development of |project| packages 5 ========================================= 6 7 Very often, developers of |project| packages are confronted with the need to 8 clone repositories locally and develop installation/build and runtime code. 9 It is recommended to create isolated environments to develop new projects using conda_ and `zc.buildout`. Tools implemented in `bob.devtools` helps automate this process. In the following we talk about how to checkout and build one or several packages from 10 their git_ source and build proper isolated environments to develop them. Then we will describe how to create a new bob package from scratch and develop existing bob packages along side it. I believe that it reflects what follows. The structure of the document at the moment is like this.
- kind of introduction
- TLDR (This explains the most complicated case, meaning making a new package from scratch and also co-develop with already existing packages.)
- How to develop only one existing bob package.
- How to co develop more that one existing bob packages.
- How to create a package from scratch.
- How to create a package from scratch and co develop with existing bob packages.
- Some information on how things are actually working.
This is what I understood from our discussion. To go from easier case to the most complicated one. If you think this logic of structure is not good, let me know what is your suggestion.
changed this line in version 14 of the diff
- doc/development.rst 0 → 100644
134 $ cd src/bob.extension 135 $ ../../bin/sphinx-build -aEn doc sphinx # make sure it finishes without warnings. 136 $ firefox sphinx/index.html # view the docs. 137 138 .. note:: 139 140 Sometimes when you are calling a function not interactively it is not acting normally. In that case import pkg_resources before importing your package. It is a known issue and we are working on it. 141 142 .. code-block:: sh 143 144 $ ./bin/python -c "import pkg_resources; import bob.blitz; print(bob.blitz)" 145 146 147 .. bob.devtools.local_development: 148 149 Local development of existing Bob packages -
This needs to appear first in this guide, before the TL;DR, which, in my view, is too long and should just contain commands.
PS: Have you tested the commands with a sample project (say bob/bob.blitz>)?
Do you mean I should put this note on the top of the page before even starting TL;DR?
The TL;DR that I put describes the most complicated case, meaning making a package from scratch and co-develop with already existing packages. That's why it is long. I can put any of the other scenarios. Let me know what is your suggestion.
changed this line in version 14 of the diff
- doc/development.rst 0 → 100644
272 .. code-block:: sh 273 274 $ cd <package> 275 $ conda activate bdt 276 $ bdt local build 277 278 279 One important advantage of using conda_ and zc.buildout_ is that it does 280 **not** require administrator privileges for setting up any of the above. 281 Furthermore, you will be able to create distributable environments for each 282 project you have. This is a great way to release code for laboratory exercises 283 or for a particular publication that depends on |project|. 284 285 Developing multiple existing |project| packages simultaneously 286 -------------------------------------------------------------- 287 It so happens that you want to develop several bob.packages against each other for your project. Let's assume you want to develop package A and B simultaneously. We assume that package A is dependent on B. First we checkout package A and build an isolated conda environment as explained in the previous section. Then edit `buildout.cfg` file (or `develop.cfg`) and add package B to it as following: changed this line in version 12 of the diff