#40 (Improve documentation about Lino)

by Luc Saffre · in Developers · assigned to Luc Saffre

Résumé

Concepts sous-jacents

#4487 (Move language selector from menu to top bar) (by Luc Saffre in Developers assigned to Luc Saffre)
#5600 (Remove lino.modlib.system from react requirements) (by Luc Saffre in Developers assigned to Luc Saffre)
#6050 (Can we remove Site.get_database_settings()?) (by Luc Saffre in Developers assigned to Luc Saffre)
#6297 (Rename setting.SITE to settings.APP?) (by Luc Saffre in Developers)

Commentaires

3 semaines, 6 jours ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed the reference page for the gfks plugin. But It's not finished.
5 mois, 1 semaine ago by Luc Saffre about #40 (Improve documentation about Lino) : One section in the manual testing suite is obsolete and needs revision: dev.lino-framework.org/mts/#avanti
5 mois, 1 semaine ago by Luc Saffre in reply to Luc Saffre about #40 (Improve documentation about Lino) : (This caused changes in almost all repositories...)
5 mois, 1 semaine ago by Luc Saffre about #40 (Improve documentation about Lino) (1 reply) : I added the pencil icon to our collection of icons and now use it in Editing a Lockable data row.
5 mois, 2 semaines ago by Luc Saffre about #40 (Improve documentation about Lino) : I did something that would take years of discussions in Django: I changed the label "System" in the menu to "Site". The label "System" disturbed me because it is simply the wrong word in this context.
5 mois, 3 semaines ago by Luc Saffre about #40 (Improve documentation about Lino) : I had a sphinx-build warning after my recent changes; to fix it, I moved the docs from lino/core/requests.py to book/src/core/requests.rst.
6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I noticed that ug contains doctest snippets but doesn't run doctests. TODO: check whether test passes on GitLab
6 mois, 2 semaines ago by Luc Saffre about #40 (Improve documentation about Lino) : I upgraded the Django links in all *.py and *.rst files from docs.djangoproject.com/en/5.2 to docs.djangoproject.com/en/6.0
7 mois, 2 semaines ago by Luc Saffre about #40 (Improve documentation about Lino) : I started to review the terms on www.synodalsoft.net/jargon/ page. OMG what a Sisyphean task!
1 année ago by Luc Saffre about #40 (Improve documentation about Lino) : I started a page Introduction to model mixins because this was missing in the Dive into Lino section.
1 année, 1 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I continued to review the Get started and Dive sections of the developer guide.
1 année, 1 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed the Introduction to tables page for @joosep.
1 année, 2 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Yesterday a recruiter talked to me about his ATS and I had to look up what that term means. Now I wrote a topics guide about it.
1 année, 2 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I did a review of the lets1 project.
1 année, 2 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : The "Read-only actions" section in Intro to actions should go to another place.
1 année, 2 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I discovered sphinx-copybutton and started using it for hg and book.
1 année, 2 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I renamed lino.mixins.duplicable.Duplicable to lino.mixins.clonable.Clonable and changed the button_text of the clone_row action from ⚇ to 🗗.
1 année, 3 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed the dev.lino-framework.org/dev/front_ends.html page.
1 année, 3 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Todo learnbyexample.github.io/practice_python_projects/preface.html
1 année, 3 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I pushed a text-intensive change "Upgrade links to Django docs from 5.0 to 5.2" to many repositories. No functional changes, only links are changed using global find & replace.
1 année, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : todo: find a better name than "trade type" because only sales and purchases are about trading while the other trade types (wages, taxes, clearings...) aren't about trading. Maybe "business type". A company can have multiple types of business with a same partner. For example a person can act as a cus...
1 année, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I worked a bit on the reference page about dev.lino-framework.org/api/ad/site.html">lino.core.site.Site and I hope it's a bit better than before... but it's still a Pandora box.
1 année, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I moved the remaining content from cg to ss. The cg is now empty and can go away.
1 année, 8 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I tidied up the [url dev.lino-framework.org/apps/noi/index.html Lino Noi Developer Guide index page] a bit.
1 année, 9 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed noi and cosi: removed docs and test from these repositories because they were pretty useless because noi and cosi are [url dev.lino-framework.org/apps/index.html privileged applications].
1 année, 10 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I moved the getlino reference documentation back from book to the doctree in the getlino repository. Because it contains tested docs, which should be together with the code. I don't remember why I moved it to the book...
2 ans, 3 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I merged book/docs/dev/table_summaries.rst into [url dev.lino-framework.org/dev/display_modes.html Introduction to display modes].
2 ans, 4 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I moved German docs from cosi/dedocs to ug/dedocs, and changed the ug from only English to "en","de".
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I now pushed my changes of the last days.
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : During the last days I have been working on [url using.lino-framework.org/apps/noi/ The Lino Noi User Guide]. I will stop now for this time. It's not finished (and never will be), but at least I have updated the obsolete things.
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Good work! I am always glad to get a second brain with the docs. I made a few changes [url gitlab.com/lino-framework/book/-/commit/d5e1e26a5c406ccc25931ad1e5fbf38eea6ef32c here], ping me for a jitsi meeting when it suits you.
2 ans, 5 mois ago by Sharif Mehedi about #40 (Improve documentation about Lino) : @luc , I'd like a review about my addition [url gitlab.com/lino-framework/book/-/commit/d81603bfc04d5ad732099b09a2d472513b38f835 here]
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I'm still busy with the documenttion about permissions. OMG! Lino is such a big beast! Explaining everything is such a huge task! More than a full-time job! And it's a quite fascinating job, by the way.
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Yesterday when moving docstrings to prosa I forgot to remove the default values from the attribute directives.
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I pushed my work. Changes in 11 repositories.
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Uff! I moved a few kilobytes of docstrings from lino/core/site.py to docs/api/ad/site.rst. The result is visible [url dev.lino-framework.org/api/index.html here] (but dont watch... it's still work in progress).
2 ans, 5 mois ago by Sharif Mehedi about #40 (Improve documentation about Lino) : @luc , The sentence about the django issue in [url dev.lino-framework.org/plugins/accounting.html#lino_xl.lib.accounting.VoucherItem.title here], which I just checked and has been fixed. So, we can probably deploy different strategy and improve this doc.
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) (1 reply) : I am replacing the word "site maintainer" by "server administrator"...
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Note that the Developer Guide has a new button [url dev.lino-framework.org/genindex.html a-z] in the upper left corner.
2 ans, 5 mois ago by Sharif Mehedi about #40 (Improve documentation about Lino) (1 reply) : in book/docs/plugins/accounting.rst, the attribute Movement.cleared does NOT have a complete description
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed the [url dev.lino-framework.org/dev/tables/index.html] page, especially changed the term "data view" back to "table".
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I made a quick review of the [url using.lino-framework.org/plugins/accounting.html] page in the user guide.
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I pushed my changes to about 10 repositories. All tests passed on my machine.
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed [url dev.lino-framework.org/dev/menu.html More about the application menu] and [url dev.lino-framework.org/dev/polls/index.html The Lino Polls tutorial]. The latter is now again listed in the Get started section (rather than being hidden near the end of the Dive into Lino section).
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I discovered that the Lino Polls tutorial is actually quite good, and that the polls and polls2 demo sites didn't show their admin_main.html because of a bug in lino.modlib.jinja.
2 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : The links in [url dev.lino-framework.org/changes/2024.html my yesterday's changelog entry] now work because I wrote some documentation. 3 hours of intensive spiritual activity and almost no quick and visible result. But under the hood the developer guide is slowly and steadily getting better each ti...
2 ans, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Today I worked on two documentation pages: [url dev.lino-framework.org/contrib/legal.html Legal considerations for contributors] and [url dev.lino-framework.org/dev/startup.html When Lino starts up].
2 ans, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : In #5523 I commented that "An action with select_rows = True may safely assume that the obj given to get_action_permission(self, ar, obj, state) is not None.", but where to put this in the documentation? Turns out that the developer guide is still very chaotic here!
2 ans, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I extended the [url dev.lino-framework.org/discover.html Discover some demo projects] page.
2 ans, 7 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I used Joy's last report to fix several bugs in the documentation
- I changed ~/repositories and ~/projects to ~/lino/env/repositories and ~/lino/lino_local - Oops, sorry, the section about install_dev_projects.sh was obsolete. I rewrote the Change the location of your repositories section.
2 ans, 7 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : After our jitsi with Joy yesterday I reviewed the doc page about [url dev.lino-framework.org/specs/getlino/startsite.html getlino startsite].
2 ans, 9 mois ago by Luc Saffre about #40 (Improve documentation about Lino) (1 reply) : The Lino framework consists of 284.000 lines of source code in 3000 files. And that's only the Python code. I generated the [url www.lino-framework.org/stats.html Statistics page] because people sometimes ask such questions.
2 ans, 9 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I replaced "https://docs.djangoproject.com/en/4.1" by "https://docs.djangoproject.com/en/5.0" in all .py and .rst files.
2 ans, 11 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I heavily optimized [url www.synodalsoft.net/] for readability.
2 ans, 11 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Today I invested a few hours into the [url dev.lino-framework.org/dev/getstarted.html Get started] section of the Developer Guide. They were really very obsolete.
2 ans, 11 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed the [url cosi.lino-framework.org/about.html About Lino Così] page because somebody on Mastodon asked for a software "to print your invoices".
3 ans, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed the developer guide for Redwan and after feedback I received some weeks ago from Fabien. We no longer let newbies install a "developer environment" and then throw it away to install a "contributor environment", we simply let them install a contributor environment directly.
3 ans, 7 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : The book isn't yet building correctly after my recent changes. I am working on it.
3 ans, 8 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Also the hosting guide should have the "four big top-level" sections (Topics, Tutorials, Recipies and Reference) inspired from [url docs.djangoproject.com/en/4.1/#how-the-documentation-is-organized].
3 ans, 8 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I made a few top-level structure changes in the Developer Guide. The whole book is the "Developer Guide". The former section "Developer Guide" is now "Dive into Lino", and the former "Contributor Guide" is now "Contribute". The former "Get aquaintained" section is now under "Reference ..> Topics".
3 ans, 9 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed and updated the welcome page of the developer guide after our meeting today. Sorry @fahmida in case you were just reading this page.
4 ans, 2 mois ago by Luc Saffre in reply to Luc Saffre about #40 (Improve documentation about Lino) : Bullshit. The code snippets aren't executed all before their output is being tested. It was because I had moved one code snippet down in the document. Now it's fixed.
4 ans, 2 mois ago by Luc Saffre about #40 (Improve documentation about Lino) (1 reply) : doctest docs/rstgen.rst is still failing because -as i learned today- the output of the code snippets in a doctest are being evaluated after having executed them all. I am still confused about what's going on there.
4 ans, 2 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I converted [url atelier.lino-framework.org/rstgen.html rstgen] docstring docs to prosa syle.
4 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed the [url dev.lino-framework.org/dev/translate/index.html How to contribute translations] page.
4 ans, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed the Basics page of the User Guide. Maybe this causes minor issues in build docs for other repositories. Didn't yet test them all. Will fix them later.
4 ans, 10 mois ago by Sharif Mehedi about #40 (Improve documentation about Lino) : lino is failing on gitlab because of some older version (v1.1.1) of etgen
4 ans, 10 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Uff, I finished to fix the warnings. See [url luc.lino-framework.org/blog/2021/1202.html my blog] for details.
4 ans, 10 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : inv bd currently has warnings in the book because the latest sphinx version is more sever about duplicate references.
4 ans, 11 mois ago by Sharif Mehedi about #40 (Improve documentation about Lino) : combining /specs/search with /plugins/search has a drawback, that is: /specs/search uses lydia as demo projects where as /plugins/search uses noi1r. As far as I can see, it is not possible to load two sites on a single script, for django.setup() is idempotent, meaning - once (django.setup is) called...
4 ans, 11 mois ago by hannes about #40 (Improve documentation about Lino) : Added some improvements to mailing part of Hosting Guide (mailman2).
4 ans, 11 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed the general structure of the [url hosting.lino-framework.org/ Hosting Guide]. Don't forget to pull before you edit it.
5 ans, 1 mois ago by Sharif Mehedi about #40 (Improve documentation about Lino) : book test suite now pass again in gitlab. At the moment the pipeline is running.
5 ans, 1 mois ago by Sharif Mehedi about #40 (Improve documentation about Lino) : Added some words and doctest about cal.Event notificaton into specs/cal.rst. see: gitlab.com/lino-framework/book/-/commit/1bfd87b4d3ef0f28909656c9295cacf6d30742cd
5 ans, 2 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I did some reorganization: (1) hosting guide: merge "Maintenance" into "Topics". and (2) developer guide: move the account plugin pages from /specs/ to /plugins/
5 ans, 3 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Most options of the tasks.py were actually already documented. I now updated the whitewall tutorial to link to the right place.
5 ans, 4 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I am almost done with the documentation about notify (for this time).
5 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I moved some content: the Developer Guide (docs of the book repository) is now published under a new [url dev.lino-framework.org/], and I moved the chapters about Lino from the Community Guide (cg) to a new repository "lf", which is now served at www.lino-framework.org. Th cg doctree no longer expla...
5 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I found yet another missing piece: we must differentiate between the Community Guide (cg) and the User Guide (ug). I now created the latter. It is hosted on [url gitlab.com/lino-framework/ug]. They are similar in that they both are docs-only repositories (they don't define a Python package) and are ...
5 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Seems that I started a next avalanche of changes in the docs. The "documentation framework" starts to meet my expectations, now I started to care about the content: a common standard for structuring the docs and reduce redundant explanations. I moved the "User Guide" section from book/docs to cg/doc...
5 ans, 5 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Wow, I had changes in almost 40 repositories today. They all have the same commit message [url luc.lino-framework.org/blog/2021/0427.html]. (I don't not recommend for my exotic practice of referring to a blog entry in a commit message... but today I would have taken half an hour more for these commi...
5 ans, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : The docs about Lino Tera were still missing after the fire at OVH. Now I restored them, but they are multilingual (en, de), and I did not want to have the German docs under their own domain name. Now they are using the same method as for www.saffre-rumma.net, where [url tera.lino-framework.org/de de...
5 ans, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I did a [url www.sphinx-doc.org/en/master/usage/builders/index.html#module-sphinx.builders.linkcheck linkcheck] run for book. It contains 260 broken links. Repairing them all would be an interesting PhD research project. Il faut imaginer Sisyphe heureux... But there are some false alerts among them:...
5 ans, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I committed my work of today. See [url luc.lino-framework.org/blog/2021/0401.html].
5 ans, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Thanks and congratulations to Charles who once more identified a flagrant missing piece in the Lino documentation: the [url www.lino-framework.org/dev/layouts/index.html Introduction to layouts] page gives only a very basic example of a detail layout. It doesn't even introduce tabbed detail views. ...
5 ans, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I hope that I finally managed to get "pp inv clean-b bd pd" to fully pass on my computer again. The first time since the fir at OVH. There was a series of technically irrelevant issues because some URLs have changed.
5 ans, 7 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I updated two pages in the Hosting Guide: Dovecot and Postfix.
5 ans, 7 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Okay the system dependencies are now done. Now it says "warning: term not in glossary: Lino application". Haha, of course, the Community Guide is not available, and probably other intersphinx dependencies as well. So I need to migrate the CG first...
5 ans, 7 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Okay, not the pipelines on GitLab are asking "Configuring slapd. Please enter the password for the admin entry in your LDAP directory. Administrator password". That's because one of the environment variables need to be set.
5 ans, 7 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : The latest pipelines (and failures) are shown here: [url gitlab.com/lino-framework/book/-/pipelines]
5 ans, 7 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : Yes, I moved the book repository from GitHub to GitLab. In your local copy of the repository you must do: $ git remote rm origin $ git remote add origin git@gitlab.com:lino-framework/book.git
The test suite and the docs build don't yet pass on GL. I will continue on this in my next session...
5 ans, 7 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I plan to move the book repository from GitHub to GitLab now soon (in 15 minutes). All contributors will need to update their 'remote' setting. I will write detailed instructions later.
5 ans, 8 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I worked on spesc/lino.rst and decided to convert the settings package of min1 into a simple settings module. Because a settings package has the irritating side effect that Site.project_dir points to the settings/ subdirectory of the project dir while the manage.py file stil is in the "real" project...
5 ans, 11 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I had a look at Imail's shared table with issues in the docs. Couldn't reproduce everything. Saw other solution than he suggessts. Wasn't always sure whether I understand what he wanted to say.
6 ans, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I reviewed the docs regarding data migration. Far from being done, but at least some vision for the general structure.
6 ans, 6 mois ago by Luc Saffre about #40 (Improve documentation about Lino) : I added a page [url community.lino-framework.org/volunteers.html Lino needs volunteer contributors] to the Community Guide. This is just a beginning, please give your feedback.