Skip to content

Commit 2597a63

Browse files
dominikbachdominikbach
authored
Merge pull request #824 from bachlab/update_documents
Update documents
2 parents 4adc3f1 + 8874700 commit 2597a63

File tree

2 files changed

+384
-0
lines changed

2 files changed

+384
-0
lines changed

‎doc/PsPM_Developers_Guide.lyx

+384
Original file line numberDiff line numberDiff line change
@@ -29234,6 +29234,390 @@ Now the script should be running ok.
2923429234
\end_inset
2923529235

2923629236

29237+
\end_layout
29238+
29239+
\begin_layout Section
29240+
Website and function descriptions
29241+
\end_layout
29242+
29243+
\begin_layout Quote
29244+
Contributed by Teddy Zhao in January 2025
29245+
\end_layout
29246+
29247+
\begin_layout Standard
29248+
This chapter describes how to contribute to the PsPM website and generate documents of function description.
29249+
\end_layout
29250+
29251+
\begin_layout Subsection
29252+
Website
29253+
\end_layout
29254+
29255+
\begin_layout Standard
29256+
The official website of PsPM is located at bachlab.github.io/pspm,
29257+
and it is hosted on GitHub at the branch
29258+
\begin_inset Quotes eld
29259+
\end_inset
29260+
29261+
gh-pages
29262+
\begin_inset Quotes erd
29263+
\end_inset
29264+
29265+
under the PsPM repository at github.com/bachlab/PsPM.
29266+
Any update to the website will need to be made by updating this branch.
29267+
The website is built up based on the website template Jekyll Gitbook:
29268+
https://sighingnow.github.io/jekyll-gitbook/.
29269+
Therefore,
29270+
further website behaviour and action changes to the PsPM website may need to refer to the original jekyll-gitbook manual.
29271+
Instead of writing fixed-content websites,
29272+
the jekyll-gitbook website template uses markdown files for generating HTML files automatically.
29273+
In early 2025,
29274+
the jekyll-gitbook template was adopted for PsPM website and live for users.
29275+
The content of the website repository includes three folders and a few individual files,
29276+
which are introduced as following.
29277+
\end_layout
29278+
29279+
\begin_layout Subsection
29280+
General structure
29281+
\end_layout
29282+
29283+
\begin_layout Standard
29284+
The PsPM website includes a main page and a few subpages.
29285+
The main page is stored at README.md,
29286+
which means the updates to the main page should be addressed by modifying README.md.
29287+
This file is located in the root folder.
29288+
Please follow the previously updated formats,
29289+
such as hyperlinks and images,
29290+
for future content updates.
29291+
The subpages are stored in _posts,
29292+
whose main description can be found in the next section.
29293+
\end_layout
29294+
29295+
\begin_layout Subsection
29296+
Folders
29297+
\end_layout
29298+
29299+
\begin_layout Subsubsection
29300+
_includes
29301+
\end_layout
29302+
29303+
\begin_layout Standard
29304+
This folder contains the required module and behaviour control files in html or json.tpl format.
29305+
Most of the files are not expected to be modified,
29306+
such as “mathjax.html”,
29307+
as they are just required for rendering the webpage components.
29308+
However,
29309+
a few files should be noticed when updating the webpage content in the future.
29310+
29311+
\end_layout
29312+
29313+
\begin_layout Standard
29314+
To update the table of content for the website,
29315+
please go to the file
29316+
\begin_inset Quotes eld
29317+
\end_inset
29318+
29319+
toc-date.html
29320+
\begin_inset Quotes erd
29321+
\end_inset
29322+
29323+
,
29324+
at around line 69 or 70,
29325+
there is a if-else clause explaining how the table of content will be generated.
29326+
Only the listed pages in this line of code will be displayed in the table of content.
29327+
\end_layout
29328+
29329+
\begin_layout Subsubsection
29330+
_layouts
29331+
\end_layout
29332+
29333+
\begin_layout Standard
29334+
This folder stores the html-based webpage templates.
29335+
There are two kinds of webpage templates,
29336+
which are “home” and “post”.
29337+
In PsPM website,
29338+
only the home page use “home” as the template,
29339+
and all other webpages should use “post”.
29340+
A markdown file is required for adding the corresponding content,
29341+
which is introduced as below.
29342+
\end_layout
29343+
29344+
\begin_layout Subsubsection
29345+
_posts
29346+
\end_layout
29347+
29348+
\begin_layout Standard
29349+
This folder stores the content for all the webpages on PsPM website except for the main page that is stored in README.md.
29350+
All the files in this folder need to be markdown files,
29351+
and the format of markdown file content can follow the currently available files.
29352+
Each file has its file name as “date-filename.md”.
29353+
The date needs to be written in the format of “YYYY-MM-DD” (American date style).
29354+
If every file has the same date,
29355+
they will be ranked alphabetically in the table of content,
29356+
otherwise it will be based on the date.
29357+
The table of content will not be automatically updated after adding new markdown files.
29358+
To update the table of content,
29359+
please check the _includes section.
29360+
\end_layout
29361+
29362+
\begin_layout Subsubsection
29363+
asset
29364+
\end_layout
29365+
29366+
\begin_layout Standard
29367+
This folder stores the required resources,
29368+
such as images,
29369+
for the website.
29370+
Images should be put at the location /assets/images,
29371+
and they need to be properly referred when being added to the webpages.
29372+
\end_layout
29373+
29374+
\begin_layout Subsection
29375+
Basic File formats
29376+
\end_layout
29377+
29378+
\begin_layout Standard
29379+
This section introduces how to write the markdown files for webpage contents.
29380+
This is given by using the README.md as an example.
29381+
\end_layout
29382+
29383+
\begin_layout Subsubsection
29384+
Header
29385+
\end_layout
29386+
29387+
\begin_layout Standard
29388+
In the line 1-5 of a markdown file,
29389+
the line 1 and line 5 should be
29390+
\begin_inset Quotes eld
29391+
\end_inset
29392+
29393+
---
29394+
\begin_inset Quotes erd
29395+
\end_inset
29396+
29397+
(three dashes).
29398+
This is the marks that show the content between them is header and can be read.
29399+
\end_layout
29400+
29401+
\begin_layout Standard
29402+
\begin_inset Graphics
29403+
filename /Users/teddy/Desktop/Screenshot 2025-02-06 at 14.51.44.png
29404+
29405+
\end_inset
29406+
29407+
29408+
\end_layout
29409+
29410+
\begin_layout Standard
29411+
The first line is the layout that will be used for displaying this webpage.
29412+
It can be either
29413+
\begin_inset Quotes eld
29414+
\end_inset
29415+
29416+
home
29417+
\begin_inset Quotes erd
29418+
\end_inset
29419+
29420+
or
29421+
\begin_inset Quotes eld
29422+
\end_inset
29423+
29424+
post
29425+
\begin_inset Quotes erd
29426+
\end_inset
29427+
29428+
.
29429+
29430+
\begin_inset Quotes eld
29431+
\end_inset
29432+
29433+
Home
29434+
\begin_inset Quotes erd
29435+
\end_inset
29436+
29437+
is used for the homepage,
29438+
and
29439+
\begin_inset Quotes eld
29440+
\end_inset
29441+
29442+
post
29443+
\begin_inset Quotes erd
29444+
\end_inset
29445+
29446+
is used for any other webpage,
29447+
such as
29448+
\begin_inset Quotes eld
29449+
\end_inset
29450+
29451+
Course
29452+
\begin_inset Quotes erd
29453+
\end_inset
29454+
29455+
or a descriptive page for a PsPM function.
29456+
\end_layout
29457+
29458+
\begin_layout Standard
29459+
The second line is the title of this webpage.
29460+
This is the displayed title of this webpage that can be used for referring to by other functions,
29461+
such as table of content generation content.
29462+
Please make sure this title is not shared by two different webpages for avoiding potential risks.
29463+
This head will be displayed as the header on the webpage,
29464+
as shown below.
29465+
For visual comfortableness,
29466+
please leave the title to be simple and relatively short for avoiding busying feeling unless required.
29467+
\end_layout
29468+
29469+
\begin_layout Standard
29470+
\begin_inset Graphics
29471+
filename /Users/teddy/Desktop/Screenshot 2025-02-06 at 15.14.02.png
29472+
width 90text%
29473+
29474+
\end_inset
29475+
29476+
29477+
\end_layout
29478+
29479+
\begin_layout Standard
29480+
The third line is the permanent link of this webpage.
29481+
If it is left as just a
29482+
\begin_inset Quotes eld
29483+
\end_inset
29484+
29485+
/
29486+
\begin_inset Quotes erd
29487+
\end_inset
29488+
29489+
,
29490+
it means this page is the default home page.
29491+
For PsPM,
29492+
a
29493+
\begin_inset Quotes eld
29494+
\end_inset
29495+
29496+
/
29497+
\begin_inset Quotes erd
29498+
\end_inset
29499+
29500+
means the link to this page is
29501+
\begin_inset Quotes eld
29502+
\end_inset
29503+
29504+
bachlab.github.com/pspm
29505+
\begin_inset Quotes erd
29506+
\end_inset
29507+
29508+
.
29509+
If it is a
29510+
\begin_inset Quotes eld
29511+
\end_inset
29512+
29513+
/ref
29514+
\begin_inset Quotes erd
29515+
\end_inset
29516+
29517+
,
29518+
then the page would be
29519+
\begin_inset Quotes eld
29520+
\end_inset
29521+
29522+
bachlab.github.com/pspm/ref
29523+
\begin_inset Quotes erd
29524+
\end_inset
29525+
29526+
.
29527+
\end_layout
29528+
29529+
\begin_layout Subsubsection
29530+
Captions and links
29531+
\end_layout
29532+
29533+
\begin_layout Standard
29534+
To insert images for webpages,
29535+
please use the following sentence.
29536+
In this sentence,
29537+
the src should be the link of the image that is normally stored within the
29538+
\begin_inset Quotes eld
29539+
\end_inset
29540+
29541+
assets
29542+
\begin_inset Quotes erd
29543+
\end_inset
29544+
29545+
folder.
29546+
The
29547+
\begin_inset Quotes eld
29548+
\end_inset
29549+
29550+
alt
29551+
\begin_inset Quotes erd
29552+
\end_inset
29553+
29554+
is the caption of the image.
29555+
\end_layout
29556+
29557+
\begin_layout Standard
29558+
\begin_inset listings
29559+
inline false
29560+
status open
29561+
29562+
\begin_layout Plain Layout
29563+
29564+
<img class="PsPM_Web" src="assets/images/PsPM_Website_Figure_1.jpg" type="image/jpg" alt="PsPM" >
29565+
\end_layout
29566+
29567+
\end_inset
29568+
29569+
29570+
\end_layout
29571+
29572+
\begin_layout Standard
29573+
To insert a hyperlink to a website,
29574+
please use the following sentence.
29575+
\end_layout
29576+
29577+
\begin_layout Standard
29578+
\begin_inset listings
29579+
inline false
29580+
status open
29581+
29582+
\begin_layout Plain Layout
29583+
29584+
[retrodictive validity](https://doi.org/10.1038/s41562-020-00976-8)
29585+
\end_layout
29586+
29587+
\end_inset
29588+
29589+
29590+
\end_layout
29591+
29592+
\begin_layout Subsubsection
29593+
Table of content generation
29594+
\end_layout
29595+
29596+
\begin_layout Standard
29597+
Please use the file
29598+
\begin_inset Quotes eld
29599+
\end_inset
29600+
29601+
toc-date.html
29602+
\begin_inset Quotes erd
29603+
\end_inset
29604+
29605+
to control the generation of table of content.
29606+
Currently,
29607+
please go to line 69–70,
29608+
where the list of items shown in the table of content is listed here.
29609+
Items will not be displayed unless they are specified here,
29610+
thus please always keep this file updated.
29611+
\end_layout
29612+
29613+
\begin_layout Standard
29614+
\begin_inset Graphics
29615+
filename /Users/teddy/Desktop/Screenshot 2025-02-07 at 03.32.35.png
29616+
width 95text%
29617+
29618+
\end_inset
29619+
29620+
2923729621
\end_layout
2923829622

2923929623
\begin_layout Section

‎doc/PsPM_Developers_Guide.pdf

751 KB
Binary file not shown.

0 commit comments

Comments
 (0)