Skip to content

Home

Jump to bottom
tobyegg edited this page Nov 20, 2022 · 16 revisions

JIPCAD Website Editing Tutorial

The intention of starting the JIPCAD website is to host and maintain JIPCAD documentation, as well as allow for a place where the amazing creations of URAP members and users are exhibited. Every JIPCAD contributor is encouraged to update and improve the JIPCAD documentation and post on the blog display your creations and detail your methods behind their creation. It's also vastly helpful to contribute to the general Q&A page to report and document any bug or bummer you have encountered while using the software so other users can avoid spending mass amounts of time reinventing the wheel. Now let's dive into how to locally host the repository, the structure of the website, and where should you put your additions.

1. Installation

The NOME website is built using docusaurs, which extends yarn, and thus requires Node.js to run.

1.0 Github

If not already installed, download Github Desktop and clone the repository to a blank folder.

1.1 Node.js

Setup:

  • Mac and Windows, download the installer for the 16.13.0 version of Node.js found on their website
    • This is found on the 5th page of the "Previous Releases" menu
    • Check all boxes during install
    • Nevermind, get NVM for Windows or NVM if on Mac, this lets you switch between and install different version with ease.
  • Linux: 64-bit and ARMv7/8 binaries are available at the above link

On any terminal, run node -v to check if it has been successfully installed

1.2 Yarn

JIPCAD.github.io is built using a legacy version of yarn, v1.22.19, meaning that classic.yarnpkg.com should be used for installation/troubleshooting information and not the modern website for v2 and more recent yarn. First time-setup:

  • Navigate to the repository folder in terminal
  • Run yarn or yarn install (they are identical commands)
  • Check if yarn is installed with yarn -v. Now that yarn is installed, running yarn or yarn install will check if yarn is up to date.

Congratulations! You've locally built JIPCAD.github.io. To host, run yarn start and a browser window will open with your version of the website. Here, you can edit files, compare to the original, and when ready, push to the repository!

1.3 Notes

  • All commands must be run on an administrator command-level; on a Windows computer with multiple profiles, this means the terminal must be right-clicked and run as administrator on any but default user.
    • A shortcut for this is to hit windows key, type "cmd", and ctrl+shift+enter
  • Do not update yarn when first installing it, this will overwrite the provided docusaurus commands. Simply run yarn to install v1.22.19
  • If the website displays warnings about "unmet peer dependency" or compiles with errors when running yarn start, uninstall node (through standard Windows/OSX uninstall app function) and reinstall v.16.13.10 (steps)
  • While the website is running locally, use ctrl+c or cntrl+pause to end the hosting.
  • "npx" commands are built into docusaurus/yarn and can be run after following the above steps. "npm" commands refer to the npm package manager, which may or may not be installed with node depending on the method of installation (version can be checked with npm -v). "nvm" commands are commands for Node Version Manager or Node Version Manager for Windows, which are two separate projects.

2. Website Structure

The current JIPCAD documentation includes the following parts

  • Documentation
    • Introduction
      • The general introduction which explains what is JIPCAD and why it's initiated.
    • Compiling
      • The compiling guide shows you the compiling procedure of the software from the source code.
    • Tutorial
      • User Guide
        • The user guide doesn't touch the code part.
        • This session includes how to use JIPCAD software.
        • Examples that tell you how to advance the JIPCAD tool.
      • Developer Guide
        • The developer guide is for those who intend to contribute to the JIPCAD code base.
        • The general mechanism of how the code works.
        • Gives you an idea of what different parts of the code do.
        • The data structures and dependencies used in the codebase.
        • Once your interest is set, which part of the code should you read and touch.
    • JIPCAD language reference
      • Configuration
        • The configurations of the JIPCAD file.
      • Numerical Parameters and Sliders
        • Use of sliders
        • Time-varying models​
      • Generators
        • How to generate all available geometric shapes
      • Rendering Specifications
      • Numerical Parameters and Sliders
      • Generators
      • Rendering Specifications
    • Error Reporting
      • As the JIPCAD software is in development, the error reporting reveals the current imperfections you should be aware of.
      • Host crashes and bugs each URAP member encounters:
        • If you have made things work, how?
        • If things unfortunately failed, which file and what operations have led to the happening?
  • Exhibition
    • The exhibition page is set up for showing all works completed by JIPCAD artists.
    • The inclusion of detailed steps which have led you to the creation of the masterpiece is appreciated.
  • Download
    • The download page keeps the Mac and Windows executables.
    • Version management should be maintained on this page to keep logging the updates and new features of JIPCAD software.

3. Website Management

3.1 Website Files

Edit the files in the corresponding folder to manage the website contents. Ensure that you are in the source branch.

The website uses docusaurus as the backbone, you could read the docusaurus doc for more instruction.

3.2 Website Deployment

In this website repo, there are two branches:

  1. deploy
    • Where the deployed built is hosted and what people see at the website.
    • Do not directly edit files at the deploy branch!!!
  2. source
    • Where the source code before the building is hosted.

Deploy to the JIPCAD.github.io page, use the following bash command:

GIT_USER=<GH username> USE_SSH=true yarn deploy
Clone this wiki locally