Revamp the software section #19

alexfoias · 2021-08-19T15:01:16Z

The purpose of this PR is to revamp the software page.

TODO after this PR:

Add other software and analysis pipeline/template projects in Software section Add other software and analysis pipeline/template projects in Software section #50
Vertically center logo on the software grid Vertically center logo on the software grid #48
Refactor gallery generation methods Refactor gallery generation methods #47
Add AxonPacking Add AxonPacking #51
List sct-pipeline under software section List sct-pipeline under software section #52

alexfoias · 2021-08-19T18:34:01Z

Not sure how to vizualize the changes on the gitbook. I tried to build it in local (gitbook build or gitbook serve) but it didn't work. I'm currently exploring other options.

jcohenadad · 2021-12-03T03:10:47Z

@alexfoias just checking if you are still working on this? (opened for a while)

alexfoias · 2021-12-03T14:29:46Z

@jcohenadad I will work to make it work with the new version of the website. This issue was opened when we were on the gitbook platform.

alexfoias · 2021-12-03T16:50:59Z

@kousu is there any way of seeing the built ? thanks

kousu · 2021-12-03T17:26:05Z

@kousu is there any way of seeing the built ? thanks

For the record, yes, and this is currently documented here:

neuro.polymtl.ca/setup.py

Lines 2 to 7 in f4dbbe4

    
           To build the docs: 
        
               pip install .[sphinx] 
        
               make html 
        
           They will end up in _build/html/

I didn't want to stick this on the main README.md because that would end up getting built in to the front page.

alexfoias · 2021-12-03T18:48:16Z

@kousu It would be nice if we could implement CI to see the various branches.

alexfoias · 2021-12-03T18:53:48Z

Screenshots of: 2f6bd49

I will have to fix the size of the images.

@jcohenadad what should I do with the software that doesn't have a logo ? For the moment I added the lab's logo given the fact that the repos are under the neuropoly organization.

jcohenadad · 2021-12-03T19:02:16Z

I will have to fix the size of the images.

indeed

@jcohenadad what should I do with the software that doesn't have a logo ? For the moment I added the lab's logo given the fact that the repos are under the neuropoly organization.

i would leave it empty

alexfoias · 2021-12-03T19:15:58Z

Screenshots from: de4cada

jcohenadad · 2021-12-03T20:48:17Z

in #19 (comment) the ratio should be kept-- also i suggest to use the same height across all logos-- more cosmetic

kousu · 2021-12-04T02:18:29Z

@kousu It would be nice if we could implement CI to see the various branches.

I had suggestions about this in the original PR:

Github Pages is too simple to handle branches.

However someone could fork the repo, and so long as they're working on master their fork should automatically go live at https://username.github.io/neuropoly-docs.

I am also not against hosting on readthedocs especially if we do want PR previews. I have no horse in the RTD / Github race, they're both just companies to me; I demo'd this way because it meant one less credential to manage; and also PRs should be the exception not the rule.

Right now I think it's not that hard to just build it locally and share via screenshot, or just by having reviewers also build it locally. I built this process assuming the vast majority of edits would be one-off commit-to-master sort of deals with no need to preview.

But like I said if you want to show off your changes live instead of via screenshot you can

Fork this repo
Go to Settings > Pages in your fork
Tell it to publish from gh-pages
Settings > Pages will give you a URL you can look at it in

And in the extremely rare case you need to compare multiple live versions, you can just make multiple forks. Github won't let you do that directly from the Fork button but you just have to make a bunch of New repos then git push from the same local repo to each.

kousu · 2021-12-04T02:23:10Z

I have an idea: what if you combined the logo and name columns? Make sure to set alt and title attributes with the markdown image syntax:

![ivadomed](../.gitbook/asserts/logo_ivadomed.png "ivadomed")

So that mousing over will pop-up the name, and that looking at it in a screenreader or text-only/braille browser will still show the title.

And then for rows without a logo, like AxonPacking, you can just leave it as-is.

kousu · 2021-12-04T02:27:48Z

Also, I would make sure to copy the logos into the assets/ folder so that the site is self-contained.

kousu · 2021-12-04T02:37:55Z

I notice that the descriptions are centered while the docs link isn't anymore. I found the reason, it's this:

neuro.polymtl.ca/_static/theme.css

Lines 85 to 88 in f4dbbe4

    
           #open-source-projects table tr > :is(th,td):is(:nth-child(3),:nth-child(4)) { 
        
             text-align: center; 
        
             min-width: 15%; /* this forces these columns to get 30%, text-wrapping the description column as necessary */ 
        
           }

because adding an extra column bumped the indexes all over. So, if you keep both logo and title columns, you'll have to bump those to 4,5 from 3,4 (but I'm still rooting over here in my tiny clown-car sized corner for merging the columns 🤡 🤡 🍰 )

jcohenadad · 2021-12-04T16:11:33Z

Another suggestion would be to organize the software page as a gallery. I find it waaay cooler.

kousu · 2021-12-04T19:16:33Z

I think a gallery is a lot messier personally. It's a lot easier to get an overview from a table.

jcohenadad · 2021-12-04T21:36:26Z

Here is the rendering of the software page as a gallery (in ef311af). The most democratic way is to vote with 👍 /👎

Updated version with the software description:

Note: I'm aware the logos need to be vertically aligned, but i wasn't able to do it. Since this is not a priority it can be addressed later in #48

kousu · 2021-12-04T22:26:31Z

conf.py

+
+
+
+# -- Custom scripts ----------------------------------------------------------


This line should be above

thanks, fixed in 176ebe5

kousu · 2021-12-04T22:29:11Z

conf.py

+
+LOGGER = logging.getLogger("conf")
+
+def build_gallery(app: Sphinx):


It's inelegant to do all this in the conf.py file, running it on every parse like this.

It would be significantly cleaner to package this script as a custom directive, stick it up on pypi, and then instead of

```{include} gallery.txt ```

do

```{gallery} - name: Spinal Cord Toolbox website: https://spinalcordtoolbox.com/ repository: https://github.com/spinalcordtoolbox/spinalcordtoolbox image: https://raw.githubusercontent.com/spinalcordtoolbox/spinalcordtoolbox/master/documentation/source/_static/img/logo_sct.png - name: ivadomed website: https://ivadomed.org repository: https://github.com/ivadomed/ivadomed image: https://raw.githubusercontent.com/ivadomed/ivadomed/master/images/ivadomed_logo.png - name: qMRLab website: https://qmrlab.readthedocs.io repository: https://github.com/qMRLab/qMRLab image: https://raw.githubusercontent.com/qMRLab/documentation/master/logo/qMR_logo_orig.png - name: Shimming Toolbox website: https://shimming-toolbox.org repository: https://github.com/shimming-toolbox image: https://raw.githubusercontent.com/shimming-toolbox/shimming-toolbox/master/docs/source/_static/img/shimming_toolbox_logo.png - name: AxonDeepSeg website: https://axondeepseg.readthedocs.io/ repository: https://github.com/neuropoly/axondeepseg image: https://raw.githubusercontent.com/neuropoly/axondeepseg/master/docs/source/_static/logo_ads-alpha.png ```

and those images should be inlined

agreed-- but i don't have the time to do it, so #47

kousu · 2021-12-04T22:29:29Z

gallery.yml

+- name: Spinal Cord Toolbox
+  website: https://spinalcordtoolbox.com/
+  repository: https://github.com/spinalcordtoolbox/spinalcordtoolbox
+  image: https://raw.githubusercontent.com/spinalcordtoolbox/spinalcordtoolbox/master/documentation/source/_static/img/logo_sct.png


These images should be inlined

i don't understand this comment (ie: what do you mean by 'inlined'?)

kousu · 2021-12-04T22:29:46Z

setup.py

+            "sphinx-design~=0.0.11",
+# pinned because of this bug https://github.com/pydata/pydata-sphinx-theme/pull/509


careful, this changed the meaning of the comment

my bad, fixed in 72c5bf1

kousu · 2021-12-04T22:31:07Z

conf.py

+    random.shuffle(projects)
+    for item in projects:
+        if not item.get("image"):
+            item["image"] = "https://jupyterbook.org/_images/logo-square.svg"


This image should be inlined

my bad, fixed in 72c5bf1

kousu · 2021-12-04T22:31:15Z

conf.py

+    LOGGER.info("building gallery...")
+    grid_items = []
+    projects = yaml.safe_load((Path(app.srcdir) / "gallery.yml").read_text())
+    random.shuffle(projects)


ah! thanks, i was wondering why they were shuffled 😅

fixed in c3e6c8c

kousu · 2021-12-04T22:36:31Z

conf.py

@@ -34,6 +34,7 @@
 extensions = [
        'myst_parser', # there's also myst_nb, which supports embedding Jupyter notebooks, but is heavier.
        'sphinx_panels',
+        'sphinx_design',


This is a strange dependency. It pulls in bootstrap? But bootstrap has already been deprecated for several years by the existence of https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Grids. If I look at the web debugger in https://sphinx-design.readthedocs.io/en/sbt-theme/grids.html#grid-options I see they're not using that at all though:

this is needed, otherwise on compilation i get:

/Users/julien/code/neuro.polymtl.ca/gallery.txt:2: WARNING: Unknown directive type "grid".

#19 (comment)

h/t #19 (review)

anticipating there will be more galleries in the future

fix software logo

af727ea

alexfoias marked this pull request as ready for review August 19, 2021 15:01

alexfoias changed the title ~~Fix software logo~~ WIP: Fix software logo Aug 19, 2021

kousu force-pushed the master branch from cceb2b0 to f2a17db Compare November 3, 2021 03:33

alexfoias and others added 2 commits December 3, 2021 11:49

add logo column

a84b52c

Merge branch 'master' into af/fix_software

4a837ba

alexfoias changed the title ~~WIP: Fix software logo~~ Fix software logo Dec 3, 2021

add logos

2f6bd49

force fixed height

de4cada

Implemented gallery view for software

ef311af

jcohenadad added 2 commits December 4, 2021 16:39

Removed temporary changes in Makefile

508f2ed

Fixed typo

f0a218e

jcohenadad changed the title ~~Fix software logo~~ Revamp the software section Dec 4, 2021

kousu reviewed Dec 4, 2021

View reviewed changes

Removed empty lines

176ebe5

#19 (comment)

jcohenadad mentioned this pull request Dec 4, 2021

Refactor gallery generation methods #47

Closed

jcohenadad added 6 commits December 4, 2021 17:51

fixed comment

72c5bf1

No more randomization of projects

c3e6c8c

h/t #19 (review)

Added software descriptions

667b9e3

Moved software description below the logo

494892b

Fixed URL to shimming toolbox repo

993d3d1

Changed gallery for gallery_software

ab7b846

anticipating there will be more galleries in the future

jcohenadad merged commit 9d6b81f into master Dec 12, 2021

jcohenadad deleted the af/fix_software branch December 12, 2021 17:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Revamp the software section #19

Revamp the software section #19

alexfoias commented Aug 19, 2021 •

edited by jcohenadad

Loading

alexfoias commented Aug 19, 2021

jcohenadad commented Dec 3, 2021

alexfoias commented Dec 3, 2021

alexfoias commented Dec 3, 2021

kousu commented Dec 3, 2021

alexfoias commented Dec 3, 2021

alexfoias commented Dec 3, 2021

jcohenadad commented Dec 3, 2021

alexfoias commented Dec 3, 2021

jcohenadad commented Dec 3, 2021

kousu commented Dec 4, 2021 •

edited

Loading

kousu commented Dec 4, 2021 •

edited

Loading

kousu commented Dec 4, 2021

kousu commented Dec 4, 2021 •

edited

Loading

jcohenadad commented Dec 4, 2021 •

edited

Loading

kousu commented Dec 4, 2021

jcohenadad commented Dec 4, 2021 •

edited

Loading

kousu Dec 4, 2021

jcohenadad Dec 4, 2021

kousu Dec 4, 2021 •

edited

Loading

kousu Dec 4, 2021

jcohenadad Dec 4, 2021

kousu Dec 4, 2021

jcohenadad Dec 4, 2021 •

edited

Loading

kousu Dec 4, 2021

jcohenadad Dec 4, 2021

kousu Dec 4, 2021

jcohenadad Dec 4, 2021

kousu Dec 4, 2021

jcohenadad Dec 4, 2021

kousu Dec 4, 2021

jcohenadad Dec 4, 2021




		# -- Custom scripts ----------------------------------------------------------


		LOGGER = logging.getLogger("conf")

		def build_gallery(app: Sphinx):

		"sphinx-design~=0.0.11",
		# pinned because of this bug https://github.com/pydata/pydata-sphinx-theme/pull/509

Revamp the software section #19

Revamp the software section #19

Conversation

alexfoias commented Aug 19, 2021 • edited by jcohenadad Loading

alexfoias commented Aug 19, 2021

jcohenadad commented Dec 3, 2021

alexfoias commented Dec 3, 2021

alexfoias commented Dec 3, 2021

kousu commented Dec 3, 2021

alexfoias commented Dec 3, 2021

alexfoias commented Dec 3, 2021

jcohenadad commented Dec 3, 2021

alexfoias commented Dec 3, 2021

jcohenadad commented Dec 3, 2021

kousu commented Dec 4, 2021 • edited Loading

kousu commented Dec 4, 2021 • edited Loading

kousu commented Dec 4, 2021

kousu commented Dec 4, 2021 • edited Loading

jcohenadad commented Dec 4, 2021 • edited Loading

kousu commented Dec 4, 2021

jcohenadad commented Dec 4, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kousu Dec 4, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jcohenadad Dec 4, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexfoias commented Aug 19, 2021 •

edited by jcohenadad

Loading

kousu commented Dec 4, 2021 •

edited

Loading

kousu commented Dec 4, 2021 •

edited

Loading

kousu commented Dec 4, 2021 •

edited

Loading

jcohenadad commented Dec 4, 2021 •

edited

Loading

jcohenadad commented Dec 4, 2021 •

edited

Loading

kousu Dec 4, 2021 •

edited

Loading

jcohenadad Dec 4, 2021 •

edited

Loading