Documentation build procedure

[martynia]

I tried to build documentation following the docs here:https://github.com/DIRACGrid/DIRAC/blob/4d98c990df0602cc627d8a36a399ec49d5e2f1c3/docs/README

It looks outdated. After correcting line 5 to read source diracos/diracosrc make htmlall still fails> There are a few errors, the first which comes up is:

  diracdoctools.Utilities:    ERROR: Error when runnning command python /home/hep/martynia/dirac_8.0.60_ui/DIRAC/src/DIRAC/ConfigurationSystem/scripts/dirac_configuration_cli.py -h: 'Traceback (most recent call last):\n  File "/home/hep/martynia/dirac_8.0.60_ui/DIRAC/src/DIRAC/ConfigurationSystem/scripts/dirac_configuration_cli.py", line 10, in <module>\n    from DIRAC.ConfigurationSystem.Client.CSCLI import CSCLI\n  File "/home/hep/martynia/dirac_8.0.60_ui/diracos/lib/python3.11/site-packages/DIRAC/ConfigurationSystem/Client/CSCLI.py", line 13, in <module>\n    from DIRAC.Core.Base.CLI import CLI, colorize\n  File "/home/hep/martynia/dirac_8.0.60_ui/diracos/lib/python3.11/site-packages/DIRAC/Core/Base/CLI.py", line 39, in <module>\n    class CLI(cmd.Cmd):\n              ^^^^^^^\nAttributeError: module \'cmd\' has no attribute \'Cmd\'\n'

This one is also worrying:

  diracdoctools.Utilities:    ERROR: Error when runnning command python /home/hep/martynia/dirac_8.0.60_ui/DIRAC/src/DIRAC/Core/scripts/dirac_apptainer_exec.py -h: 'Traceback (most recent call last):\n  File "/home/hep/martynia/dirac_8.0.60_ui/DIRAC/src/DIRAC/Core/scripts/dirac_apptainer_exec.py", line 91, in <module>\n    main()\n  File "/home/hep/martynia/dirac_8.0.60_ui/diracos/lib/python3.11/site-packages/DIRAC/Core/Base/Script.py", line 55, in __call__\n    raise NotImplementedError("Something is very wrong")\nNotImplementedError: Something is very wrong\n'

It looks like I'm using incorrect diracdoctools somehow.

@andresailer , what is the correct procedure to build the docs ? The test above was done with an up-to-date integration branch.

[andresailer]

Hi @martynia

This line is wrong in the documentation:

-   export PYTHONPATH=$PWD/diracdoctools:$PYTHONPATH
+   export PYTHONPATH=$PWD:$PYTHONPATH

Can you try with that?

[martynia]

OK,
I installed the UI with the version specified below, then (I've got DIRAC/ checked out in the UI directory):

[martynia@lx04 dirac_8.0.60_ui]$ source diracos/diracosrc
(base) [martynia@lx04 dirac_8.0.60_ui]$ cd DIRAC/docs/
(base) [martynia@lx04 docs]$ export PYTHONPATH=$PWD:$PYTHONPATH
(base) [martynia@lx04 docs]$ make htmlall

The first error is not there anymore, however the next one is still there:
diracdoctools.Utilities: ERROR: Error when runnning command python /home/hep/martynia/dirac_8.0.60_ui/DIRAC/src/DIRAC/Core/scripts/dirac_apptainer_exec.py -h: 'Traceback (most recent call last):\n File "/home/hep/martynia/dirac_8.0.60_ui/DIRAC/src/DIRAC/Core/scripts/dirac_apptainer_exec.py", line 91, in <module>\n main()\n File "/home/hep/martynia/dirac_8.0.60_ui/diracos/lib/python3.11/site-packages/DIRAC/Core/Base/Script.py", line 55, in __call__\n raise NotImplementedError("Something is very wrong")\nNotImplementedError: Something is very wrong\n'

There are more errors, some are DiracX related. Do I need to checkout DiracX as well ??

cheers, JM

[martynia]

Ah, yes. I tried to build the integration branch. This is where I contributed to the docs ;-)

[martynia]

OK Andre,

1. From the docs in README, I need the UI, right? I created one. I sourced diracos.
2. I need my working branch where the docs are. I happen to have it my dirac_8.0.60_ui directory, hence a cd statement in the command sequence I listed above:

source diracos/diracosrc
cd DIRAC/docs/

followed by export and make htmlall. Any possible problems with this setup ?

[sfayer]

You get the Something is very wrong error if you do an editable pip install and change between tags/branches where the package entrypoint list has changed (e.g. because the dirac_apptainer_exec command has been added). Try doing a pip uninstall & install of the DIRAC module again to properly rebuild the entrypoint list (and maybe avoid editable installs entirely in this instance).

Regards,
Simon

[andresailer]

I am afraid DIRAC UI sounds like a gridpp'ism.
Here we call this a Client cf. https://github.com/orgs/DIRACGrid/projects/22?pane=issue&itemId=91452213 ?

But apparently the phrase "appropriate" is also not clear...
"Appropriate" means appropriate for the version of the documentation you want to build. You cannot build the documentation for integration with a v8 client. In fact, you need a client that is exactly as the documentation you want to build.

Therefore you need to run

pip install -e .[testing]

in you checked out folder of DIRAC to update (among other things) the console_scripts.
Like written here https://dirac.readthedocs.io/en/latest/DeveloperGuide/DevelopmentEnvironment/DeveloperInstallation/editingCode.html#installing-the-local-version

[martynia]

@sfayer I don't do an editable install (Daniela's official UI instructions don't do that). I started a new UI/client installation in a fresh directory and check out DIRAC.

[marianne013]

To be fair to me, we have some instructions on how to set up DIRAC in development mode:
https://github.com/ic-hep/gridpp-dirac-users/wiki/Setting-up-DIRAC-in-development-mode
The only problem is I haven't tried to rebuild the documentation a long time, so they are probably a bit out of date.
And yes DIRAC UI is what our users call the client, seems rather intuitive to me, no ?

[martynia]

Build finished. The HTML pages are in build/html.

I used a client/UI from the last hackathon && my integration branch. Followed the new instructions.
I did need sphinx extensions (pip install sphinx_rtd_theme sphinx_design)
I had an error when installing an editable (pip install -e .[testing]):

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
opensearch-py 2.2.0 requires urllib3<2,>=1.21.1, but you have urllib3 2.3.0 which is incompatible.
elasticsearch 7.13.4 requires urllib3<2,>=1.21.1, but you have urllib3 2.3.0 which is incompatible.

Can't tell how it affects the docs.