doc landing page that looks like a homepage and does not simply repeat the sidebar #1761

ramcdougal · 2022-04-04T16:10:23Z

This is a pull-request but also a request for comments.

View the latest version live at: https://nrn.readthedocs.io/en/new-docs-homepage/

Proposed readthedocs landing page that highlights NEURON capabilities and installation:

Currently it's a massive list (all the stuff from the list remains accessible in the above via the links in the sidebar):

This addresses one task in #1728

Thoughts?

…t the sidebar

ramcdougal · 2022-04-04T16:19:44Z

Image from @jamesgking

codecov-commenter · 2022-04-04T16:27:12Z

Codecov Report

Merging #1761 (6d0df4b) into master (8387a7b) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1761   +/-   ##
=======================================
  Coverage   45.39%   45.39%           
=======================================
  Files         551      551           
  Lines      113144   113144           
=======================================
  Hits        51358    51358           
  Misses      61786    61786

📣 Codecov can now indicate which changes are the most critical in Pull Requests. Learn more

Helveg · 2022-04-05T09:45:20Z

Can I view a build of these docs anywhere?

ramcdougal · 2022-04-05T09:56:30Z

Can I view a build of these docs anywhere?

Good idea. It should be available at https://nrn.readthedocs.io/en/new-docs-homepage/ ~~in half an hour or so~~.

To be clear, this particular pull request is only for the readthedocs homepage changes. It's separate because (1) people will likely have opinions, and (2) #1728 is massive and will not be completed in entirety at any point soon.

Edit: it's available now.

Helveg

Good landing page! I think it could still promote absolute intro level links more, like a prominent link/card to a Getting Started Guide, Sections, mechanisms, connections, ... whatever we think a user must know, explained for absolute beginners.

Something like I did here (the fancy landing page cards are about the only finished things in my docs, the rest is incomplete 😉 ); it very clearly helps new users find parts of the docs they need to get familiar with concepts. It lays out a plan for them to get from being complete novices, to beginner users comfortable with the basics of each feature. If they then need more information, they should find the topics in the ToC/sidebar; or very quickly find something in a complete and modern API reference.

Helveg · 2022-04-05T09:58:03Z

docs/index.rst

+
+.. raw:: html
+
+   <div id="downloadMacOS" style="display:none">


I don't like that the other OS instructions are completely inaccessible. Think eg someone trying to install on a VM. There are several plugins for tabs in sphinx, we could use one, and by default select the tab associated to the host OS, but then users can switch tabs to see the instructions for other platforms.

I like the tabs idea. Can you point to an example?

I would recommend sphinx-design: A brand new framework that introduces Google's Material Design spec for several themes, and the RtD theme is supported: https://sphinx-design.readthedocs.io/en/rtd-theme/

If not there are several other candidates that do (code) tabs:

https://github.com/executablebooks/sphinx-tabs

https://github.com/coldfix/sphinx-code-tabs (not that well maintained)

Looks like with sphinx-design you can use a name field to set a referenceable name, that you could use to query the tab elements in the DOM. If you open the dev tools on the doc page, you can see each tab has a radio element associated with it, if you select it you can trigger its click event and the tab changes.

Tabs are in the latest update. Give readthedocs a bit to catch up.

Looks nice! Thanks @Helveg for pointing out that!

ramcdougal · 2022-04-05T10:11:58Z

fancy landing page cards

Those do look nice.

To be honest, I think a lot of our absolute beginner level stuff is out of date in terms of what is good practice and I'm hesitant to move it over and link to it without a rethink.

Helveg · 2022-04-05T10:14:54Z

fancy landing page cards

Those do look nice.

To be honest, I think a lot of our absolute beginner level stuff is out of date in terms of what is good practice and I'm hesitant to move it over and link to it without a rethink.

I think that calls for a doc hackathon ;) Fly me over!

alexsavulescu

🚀

The PNG image is rather big (~1.1MB). We should compress it.

alexsavulescu · 2022-04-05T10:13:08Z

docs/index.rst

+      </p>
+      <p>
+         Alternatively, 
+         <a href="https://github.com/neuronsimulator/nrn/releases/download/8.1.0/nrn-8.1.0-macosx-10.9-universal2-py-38-39-310.pkg">download macOS installer</a>


Would be nice to have a generic link that points to latest pkg (thus avoiding updating the docs after each release)

Do we have such a link?

did a quick google search and came up with nothing. There was git.io backed by GitHub but it was discontinued.

And if I think about, it's not that easy to manage wrt different ReadTheDocs versions..

Would this make sense:

Suggested change

<a href="https://github.com/neuronsimulator/nrn/releases/download/8.1.0/nrn-8.1.0-macosx-10.9-universal2-py-38-39-310.pkg">download macOS installer</a>

head over to <a href="https://github.com/neuronsimulator/nrn/releases/">NEURON GitHub Releases</a> and download the desired macOS package installer from `Assets`

Not really, because we want official versions to match RTD tags

Would this make sense:

Personally I think install links ought to take you directly to the installer not another page to search through.

nightly.link

Arguably if you're viewing documentation for version X it should take you to the X installer not the latest.

I'm kind of ok with Mac and Linux taking you to a giant page with all versions since you can just pip install them... But for Windows, IMO we shouldn't make them search for the only way to install it.

Personally I think install links ought to take you directly to the installer not another page to search through.

Totally agree. Just thinking about the extra maintenance here.

Agree re: maintenance. It's a real issue; the NEURON website was never updated for 8.0.2 because we just missed doing the update and didn't notice until it was time for 8.1.

docs/index.rst

alexsavulescu · 2022-04-05T10:15:29Z

docs/index.rst

+      </p>
+   </div>
+   <div id="downloadWindows" style="display:none">
+      <a class="button" href="https://github.com/neuronsimulator/nrn/releases/download/8.1.0/nrn-8.1.0.w64-mingw-py-36-37-38-39-310-setup.exe">Download Windows installer (64 bit)</a>


Would be nice to have a generic link that points to latest exe (thus avoiding updating the docs after each release)

Co-authored-by: Alexandru Săvulescu <[email protected]>

ramcdougal · 2022-04-05T11:05:16Z

The PNG image is rather big (~1.1MB). We should compress it.

This has been replaced with a high quality jpg. I don't notice any compression artifacts.

docs/python/index.rst

Most of the comments are addressed?

* add an action item for `docs/index.rst`

doc landing page that looks like a homepage and does not simply repea…

8ef0610

…t the sidebar

ramcdougal requested review from nrnhines and alexsavulescu April 4, 2022 16:10

ramcdougal requested review from adamjhn, Helveg and pramodk April 4, 2022 16:20

ramcdougal requested a review from jamesgking April 4, 2022 16:35

added missing word

c039291

ramcdougal mentioned this pull request Apr 4, 2022

NEURON documentation plan #1728

Open

41 tasks

Helveg approved these changes Apr 5, 2022

View reviewed changes

alexsavulescu previously requested changes Apr 5, 2022

View reviewed changes

ramcdougal and others added 2 commits April 5, 2022 06:21

Update docs/index.rst

5e2d012

Co-authored-by: Alexandru Săvulescu <[email protected]>

switched from 1.1 MB png to 271 K high quality jpg

68d2589

pramodk requested changes Apr 5, 2022

View reviewed changes

docs/python/index.rst Show resolved Hide resolved

ramcdougal added 4 commits April 5, 2022 11:18

installation tabbed view via sphinx-design

0d713eb

added link with instructions on building from source

82b43dd

removed unnecessary parens

efc2ecf

Added a link to the forum

6d0df4b

ramcdougal mentioned this pull request Apr 6, 2022

How should we avoid creating repetitive large binary blobs in the repository? #1767

Open

Merge branch 'master' into new-docs-homepage

7162bd2

ramcdougal requested review from pramodk and alexsavulescu April 8, 2022 22:07

pramodk approved these changes Apr 9, 2022

View reviewed changes

ramcdougal merged commit 415a69c into master Apr 9, 2022

ramcdougal deleted the new-docs-homepage branch April 9, 2022 13:34

alexsavulescu added a commit that referenced this pull request Apr 11, 2022

Update release template following #1761

264af1b

* add an action item for `docs/index.rst`

ramcdougal pushed a commit that referenced this pull request Apr 11, 2022

Update release template following #1761 (#1774)

83c9304

* add an action item for `docs/index.rst`

alexsavulescu mentioned this pull request Jun 29, 2022

NEURON 8.2.0 release #1879

Closed

19 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc landing page that looks like a homepage and does not simply repeat the sidebar #1761

doc landing page that looks like a homepage and does not simply repeat the sidebar #1761

ramcdougal commented Apr 4, 2022 •

edited

Loading

ramcdougal commented Apr 4, 2022

codecov-commenter commented Apr 4, 2022 •

edited

Loading

Helveg commented Apr 5, 2022

ramcdougal commented Apr 5, 2022 •

edited

Loading

Helveg left a comment •

edited

Loading

Helveg Apr 5, 2022 •

edited

Loading

ramcdougal Apr 5, 2022

Helveg Apr 5, 2022

Helveg Apr 5, 2022 •

edited

Loading

ramcdougal Apr 5, 2022

pramodk Apr 9, 2022

ramcdougal commented Apr 5, 2022

Helveg commented Apr 5, 2022

alexsavulescu left a comment

alexsavulescu Apr 5, 2022

ramcdougal Apr 5, 2022

alexsavulescu Apr 5, 2022

alexsavulescu Apr 5, 2022

alexsavulescu Apr 5, 2022

alexsavulescu Apr 5, 2022

ramcdougal Apr 5, 2022

ramcdougal Apr 5, 2022

alexsavulescu Apr 5, 2022

ramcdougal Apr 5, 2022

alexsavulescu Apr 5, 2022

ramcdougal commented Apr 5, 2022

	<a href="https://github.com/neuronsimulator/nrn/releases/download/8.1.0/nrn-8.1.0-macosx-10.9-universal2-py-38-39-310.pkg">download macOS installer</a>
	head over to <a href="https://github.com/neuronsimulator/nrn/releases/">NEURON GitHub Releases</a> and download the desired macOS package installer from `Assets`

doc landing page that looks like a homepage and does not simply repeat the sidebar #1761

doc landing page that looks like a homepage and does not simply repeat the sidebar #1761

Conversation

ramcdougal commented Apr 4, 2022 • edited Loading

ramcdougal commented Apr 4, 2022

codecov-commenter commented Apr 4, 2022 • edited Loading

Codecov Report

Helveg commented Apr 5, 2022

ramcdougal commented Apr 5, 2022 • edited Loading

Helveg left a comment • edited Loading

Choose a reason for hiding this comment

Helveg Apr 5, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Helveg Apr 5, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ramcdougal commented Apr 5, 2022

Helveg commented Apr 5, 2022

alexsavulescu left a 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

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

ramcdougal commented Apr 5, 2022

ramcdougal commented Apr 4, 2022 •

edited

Loading

codecov-commenter commented Apr 4, 2022 •

edited

Loading

ramcdougal commented Apr 5, 2022 •

edited

Loading

Helveg left a comment •

edited

Loading

Helveg Apr 5, 2022 •

edited

Loading

Helveg Apr 5, 2022 •

edited

Loading