(towards #2543) Simplify Introduction documentation #2770
Conversation
…provements to other sections
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #2770 +/- ##
==========================================
+ Coverage 99.87% 99.88% +0.01%
==========================================
Files 355 355
Lines 49324 49321 -3
==========================================
+ Hits 49260 49263 +3
+ Misses 64 58 -6 ☔ View full report in Codecov by Sentry. |
sergisiso
force-pushed
the
2543_refresh_getting_going
branch
from
3d4a579
to
73a3282
Compare
|
@arporter @hiker This is ready for review. A bit unfortunately the linkcheck does not pass because the last commit updated a link to https://github.com/stfc/PSyclone/tree/master/tutorial/practicals/generic which won't exist until itself is merged, but you can check in the previous commit that the tests pass with the warning as errors flags. |
There was a problem hiding this comment.
Nice job Sergi. Thanks very much for all your work on improving the documentation.
Mostly small things. The only concern I have is that the funky new 'tab' option doesn't render very well in latexpdf but perhaps we can tweak it (or just live with it)?
docs build fine for me (and this is now tested in the CI which is great).
| @@ -66,11 +66,18 @@ jobs: | |||
| - run: sudo apt-get install -y graphviz doxygen | |||
| - run: python -m pip install --upgrade pip | |||
| - run: pip install .[doc] | |||
| # First we need a first build and launching a server, otherwise the | |||
There was a problem hiding this comment.
"...we need to build the docs and then launch a server..."
| # Now we can check for warnings and broken links | ||
| - run: cd doc/user_guide; make html SPHINXOPTS="-W --keep-going" | ||
| - run: cd doc/developer_guide; make html SPHINXOPTS="-W --keep-going" | ||
| # - run: cd doc/reference_guide; make html |
There was a problem hiding this comment.
Perhaps a TODO referencing #1280 ?
| * The ``psyclone`` :ref:`script <psyclone_command>` is located | ||
| in ``<python-base-prefix>/bin`` directory (depending on your Linux | ||
| distribution, you may need to add this location to your ``$PATH``). | ||
| please see :ref:`Installation section in the Developer Guide <dev-installation>`. |
| expressions as ``fparser`` does not fully parse these (see | ||
| `here <https://github.com/pyparsing>`__ for more information). | ||
| For more information about using ``pip`` or encapsulating the installation | ||
| in its own ``virtual environment`` we recomment reading the |
|
|
||
| > pip uninstall pyparsing | ||
| For more information about how to use Spack we recommend readign the |
|
|
||
| PSyclone provides a hands-on tutorial. The easiest way to follow it is reading | ||
| the `Readme files in github <https://github.com/stfc/PSyclone/tree/master/tutorial/practicals>`_. | ||
| The tutorial is divided in two sections, a first section that introduces |
| @@ -749,21 +800,3 @@ For more details see the ``examples/nemo/README.md`` file. | |||
| Note that these scripts are here to support the ongoing development of the | |||
| NEMO API in PSyclone. They are *not* intended as 'turn-key' solutions but | |||
There was a problem hiding this comment.
Please update. Perhaps 'ongoing development of PSyclone to transform NEMO source.'?
| @@ -749,21 +800,3 @@ For more details see the ``examples/nemo/README.md`` file. | |||
| Note that these scripts are here to support the ongoing development of the | |||
| NEMO API in PSyclone. They are *not* intended as 'turn-key' solutions but | |||
| as a starting point. | |||
There was a problem hiding this comment.
Please also update the other mentions of 'NEMO API' in the SIR and Kernel Data Extraction sections above this one.
| @@ -81,10 +81,11 @@ def have_graphviz(): | |||
| ''' Whether or not the system has graphviz installed. Note that this | |||
There was a problem hiding this comment.
Please update this docstring - it is now checking that the library is installed (since the bindings are now a mandatory dependency).
| @@ -35,6 +35,6 @@ | |||
|
|
|||
| # Top-level Makefile to test all of the NEMO hands-on tutorials. | |||
There was a problem hiding this comment.
"hands-on tutorials for transforming generic code." perhaps?
Added "warnings as errors" in the shpinx CI job
Renamed "nemo" to "generic" in tutorials and lib folders.
I removed lots of documentation that seem unneeded: two files where not used, some explanation e.g. how to use venvs is better with a link to an authoritative the source, how to install each dependency separately is probably not needed....
Merged tutorials and examples sections and rewrote tutorials part
I made termcolour and graphviz standard dependencies
I started using sphinx tabs for alternative options, see image: