diff --git a/.github/ISSUE_TEMPLATE/documentation-issue.yml b/.github/ISSUE_TEMPLATE/documentation-issue.yml new file mode 100644 index 0000000..dc3152e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation-issue.yml @@ -0,0 +1,68 @@ +name: Documentation Issue +description: Suggest improvements or report problems with the Gephi documentation +title: "[Documentation]: " +labels: [] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to help improve Gephi's documentation! + + - type: dropdown + id: issue-type + attributes: + label: Issue Type + description: What type of issue are you submitting? + options: + - Documentation Suggestion + - Report a Problem + - Question about Documentation + - Other + validations: + required: true + + - type: dropdown + id: documentation-area + attributes: + label: Documentation Area + description: Which part of the documentation does this concern? + options: + - Gephi Desktop - User Manual + - Gephi Desktop - Plugin Development + - Gephi Desktop - Developer Documentation + - Gephi Lite - User Manual + - Gephi Lite - Integration/Deployment + - Website/General + - Not sure + validations: + required: true + + - type: textarea + id: description + attributes: + label: Description + description: Please provide a clear and detailed description of your suggestion or the problem you encountered. + placeholder: | + - What did you expect to find in the documentation? + - What is missing, unclear, or incorrect? + - What improvements would you suggest? + validations: + required: true + + - type: textarea + id: location + attributes: + label: Location (if applicable) + description: If this concerns a specific page, please provide the URL or page title. + placeholder: "e.g., https://gephi.org/docs/... or 'Import CSV Data' page" + validations: + required: false + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Add any other context, screenshots, or examples that might be helpful. + validations: + required: false + diff --git a/.gitignore b/.gitignore index af7f3dd..0701c80 100644 --- a/.gitignore +++ b/.gitignore @@ -1,8 +1,8 @@ # Dependencies -/node_modules +node_modules # Production -/build +build # Idea .idea diff --git a/README.md b/README.md index aaba2fa..b20e904 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,46 @@ -# Website +# Gephi documentations websites -This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. +This repository is for the gephi projects documentation, with one site for Gephi (desktop) and an other one for Gephi-Lite. +In the futur, we can have others. -### Installation +Each of those sites are a docusaurus instance. -``` -$ yarn -``` +## How to use it -### Local Development +It's a javascript mono-repo project. +Before all, you need to install the project's dependencies ``` -$ yarn start +$> npm install ``` -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. +There are 3 main commands in the project -### Build +### npm start ``` -$ yarn build +$> npm start ``` -This command generates static content into the `build` directory and can be served using any static contents hosting service. +It starts the project in dev mode, so you will have the hot reload feature. +Under the hood, it starts the docusaurus instance for geph & gephi-lite, as well as a vite server that serves the root index.html files and has a proxy for each docusaurus instance. -### Deployment +Open the url http://localhost:5173 -Using SSH: +### npm run build + +It builds the static website inside the `/build` directory. ``` -$ USE_SSH=true yarn deploy +$> npm run build ``` -Not using SSH: +### npm run preview + +It runs a webserver that serves the `/build` directory. So it should be used after a `npm run build` to preview the build ``` -$ GIT_USER= yarn deploy +$> npm run preview ``` -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. +Open the url http://localhost:5174 \ No newline at end of file diff --git a/docs/Developer_Documentation/Developer_Handbook.md b/docs/Developer_Documentation/Developer_Handbook.md deleted file mode 100644 index 0430da8..0000000 --- a/docs/Developer_Documentation/Developer_Handbook.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -id: developer_handbook -title: Developer Handbook -sidebar_position: 1 ---- - -This page explains how to contribute to Gephi's development. - -## How to download the development version of Gephi - -### Prerequisites - -- Note: Gephi uses multi-platforms tools, so all the following steps should be the same (well, mostly) whatever the OS you are running -- First, you will need [git](http://git-scm.com/download) to download the files. -- You also need [Netbeans 8.0+](http://netbeans.org/) - -### Getting the source code - -- Read the full instructions: [[Checkout Code]] - -Now you should have a Gephi fork and a master branch. - -Set up your account credentials to Git: -```sh -git config --global user.name "Firstname Lastname" -git config --global user.email "your_email@youremail.com" -``` - -### Compiling and Running Gephi - -Read full instructions: [[Configuring NetBeans]] - -## How to create and publish your own feature - -### Configure your forked repository - -- You’ve successfully forked the Gephi repository and got the code in a gephi folder by doing - -``git clone git@github.com:username/gephi.git`` - -When a repo is cloned, it has a default remote called origin that points to your fork on GitHub, not the original repo it was forked from. To keep track of the original repo, you need to add another remote named upstream: - -```sh -cd gephi -git remote add upstream git://github.com/gephi/gephi.git -git fetch upstream master -``` - -This keeps your fork up to date. Each time you run ``git fetch upstream master`` it downloads the latest changes from the main repository (not your fork). Note that this does NOT change any of your files. You'll need a merge to actually apply the latest changes to your fork. - -### Push commits - -When you work on the code, commit often! -The commit process is straightforward. First add all the files you want to include in your commit: - -``git add .`` - -Then commit these files - -``git commit -m "This is my first commit hourray"`` - -Run git status often to see what your repository is up to. -Your commits are local. To send them to GitHub run: - -``git push origin master`` - -### Merge from the main repository - -When we update the main gephi repository, your fork doesn't get updated automatically. To merge the latest commits to your fork, run a merge from upstream: - -```sh -git fetch upstream master -git merge upstream/master -``` - -To fetch and merge in one line, simply run - -``git pull upstream master`` - -When you merge, you may run into conflicts. This is normal if you worked on the same files. -Note that ``git fetch upstream`` or ``git pull upstream`` will download the data from all branches, which you probably don't need. That's why we add 'master' to specify which branch to fetch to. - -### Send pull requests - -That's the standard and easiest way to contribute to the project. It's fully integrated into GitHub and well explained [here](http://help.github.com/send-pull-requests/). - -## How to contribute to the main project - -When you are a member of the gephi team, you have the write rights on the main repository. Instead of submitting pull requests you simply commit to the repository, including the master branch. -Change your upstream push url to authenticated version: - -``git remote set-url upstream git@github.com:gephi/gephi.git`` - -Push to the master branch. Make sure you pulled to the latest revision before (git pull upstream master). - -``git push upstream master`` \ No newline at end of file diff --git a/docs/Developer_Documentation/index.md b/docs/Developer_Documentation/index.md deleted file mode 100644 index c607771..0000000 --- a/docs/Developer_Documentation/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: index -title: Introduction -sidebar_position: 1 ---- - -Intro \ No newline at end of file diff --git a/docs/Plugins/Add_a_module_panel.md b/docs/Plugins/Add_a_module_panel.md deleted file mode 100644 index 1a7f6d6..0000000 --- a/docs/Plugins/Add_a_module_panel.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -id: Add_a_module_panel -title: Add a module panel -sidebar_position: 12 ---- - -How to create a panel for plugin features, similar to Ranking, Graph or Layout? It is easy and fully integrated in Netbeans. Create your panel class and use Netbeans IDE to design the user interface. This page also explains how to work with the **Perspective** system. - -![800px-add-module-panel](/docs/Plugins/Add_a_module_panel/00_800px-add-module-panel.png) - - -- **Step 1**: Right click on your module and select **New > Other...** and find **Window** like showed in the step 1 below. The window wizard asks where to put your panel. You can use already defined modes (i.e. positions): - * graphmode: Centered, full-size - * rankingmode: Top Left position - * layoutmode: Bottom Left position - * timelinemode: Below others, at the bottom - * filtersmode: Bottom Right - * contextmode: Top Right - -![add-module-panel1](/docs/Plugins/Add_a_module_panel/01_add-module-panel1.png) - -- **Step 2**: Then check options about the panel policy showed in step2 and click on **Next**. - -![add-module-panel2](/docs/Plugins/Add_a_module_panel/02_add-module-panel2.png) - -- **Step 3**: Fill the **Class Name**, the system shows which files are created. Your panel is a **TopComponent** subclass. - -![add-module-panel3](/docs/Plugins/Add_a_module_panel/03_add-module-panel3.png) - -- **Step 4**: Click on **Finish**, files are created and you're invited to design your panel with Netbeans editor. - -![add-module-panel-design](/docs/Plugins/Add_a_module_panel/04_add-module-panel-design.png) - -Your panel is now created and automatically registered. Start Gephi with your plugin and your panel is visible. - -## Register in a Perspective - -**Overview, Data Laboratory** and **Preview** are perspectives in Gephi. A perspective is simply a set of panels that works together. When users change the perspective, some panels are hidden and others are showed. When you define a new panel above, it is not part of a perspective and therefore is always visible, regardless which perspective you are. Follow the steps to associate your panel with a perspective. - -1. Add **Desktop Perspective** as a new module dependency. Right-click on your module and Properties. -2. Go to your `TopComponent` sources and add `PerspectiveMember` as interface. -3. Add the `@ServiceProvider` annotation to be registered by the system and implement methods (note: you will need to add the 'Desktop Perspective' to the Module Dependencies [screenshots](http://activeintelligence.org/blog/archive/gephi-howto-Add_a_module_panel-dependency/)). - -```java -@ServiceProvider(service=PerspectiveMember.class) -public final class MyTopComponent extends TopComponent implements PerspectiveMember { -... -``` - -Implement `open()` and `close()` methods like below to attach the component to the `LaboratoryPerspective`, works also for `OverviewPerspective` and `PreviewPerspective`: - -```java -public boolean open(Perspective perspective) { - return perspective instanceof LaboratoryPerspective; -} -public boolean close(Perspective perspective) { - return true; -} -``` - -Specifically use `close()` method if you want your panel to be visible on several perspectives. - -## Branding - -### Change panel title - -Open the **Bundle.properties** file in your module and update **CTL_MyTopComponent** key. - -### Set Icon - -In the **TopComponent** sources, uncomment the following line and set the icon path. - -```java -setIcon(ImageUtilities.loadImage(ICON_PATH, true)); -``` - -## Links - -- [TopComponent in Netbeans Wiki](http://wiki.netbeans.org/DevFaqWindowsTopComponent) - -- [How to create a new mode](http://blogs.sun.com/geertjan/entry/creating_a_new_mode_in) diff --git a/docs/Plugins/Add_a_submenu.md b/docs/Plugins/Add_a_submenu.md deleted file mode 100644 index 3afb891..0000000 --- a/docs/Plugins/Add_a_submenu.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -id: Add_a_submenu -title: Add a submenu -sidebar_position: 13 ---- - -From a plugin it is easy to add a menu in the menubar, for instance in **Plugins**. If you wanna add your action in a already existing menu, like **Generate**, don't follow this HowTo but look more how to create a new Generator, as the submenus may be created dynamically. - -## Create Action and Menu - -- **Step 1**: Right click on your module and select **New > Other...** and find **Action** like showed in the step 1 below. The action wizard will create everything necessary to register your action in the system and create the submenu. - -![addsubmenu-new-action](/docs/Plugins/Add_a_submenu/00_addsubmenu-new-action.png) - -- **Step 2**: Then click on **Next**, be sure **Always Enabled** is checked and **Next** again. -- **Step 3**: In the **Menu** option, select where you want your submenu to be put. Select **Plugins** to be put in this menu. - -![addsubmenu-new-action-gui](/docs/Plugins/Add_a_submenu/01_addsubmenu-new-action-gui.png) - -- **Step 4**: Click on **Next** and fill the class name, as well as the display name. - -![addsubmenu-new-action-name](/docs/Plugins/Add_a_submenu/02_addsubmenu-new-action-name.png) - -- **Step 5**: Finally, click on **Next** to create the file. - -![addsubmenu-new-action-result](/docs/Plugins/Add_a_submenu/03_addsubmenu-new-action-result.png) - -*Result* - -## Fill Action - -The precedent step created the **MyAction.java** file in your module. Implement something in the action to be executed when users click on the menu. In the example below an empty dialog is showed, using **Dialogs API**. Include **Dialogs API** as a dependency of your module if you want to use it. - -```java -public final class MyAction implements ActionListener { - - public void actionPerformed(ActionEvent e) { - //Do something - for instance display a dialog - DialogDescriptor dd = new DialogDescriptor(new JPanel(), "My Dialog", false, null); - DialogDisplayer.getDefault().notify(dd); - } -} -``` \ No newline at end of file diff --git a/docs/Plugins/Build_a_plugin_without_Gephi_source_code.md b/docs/Plugins/Build_a_plugin_without_Gephi_source_code.md deleted file mode 100644 index 1bc56c7..0000000 --- a/docs/Plugins/Build_a_plugin_without_Gephi_source_code.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -id: Build_a_plugin_without_Gephi_source_code -title: Build a plugin without Gephi source code -sidebar_position: 14 ---- - -It is possible to build a plugin using only binary installation of Gephi. The principle is to compile the plugin using the Gephi binary installation as a NetBeans platform. - -## Prerequisites - -First, you need a Gephi binary installation, such as the one that can be downloaded at https://gephi.org - -## Registering Gephi as a NetBeans Platform - -Open the "Tools|NetBeans Platforms" dialog, click on "Add Platform...", and choose the directory containing the Gephi binary installation. Note that when the NetBeans IDE detects a NetBeans Platform in a directory, the "Platform Name" label is filled with the identifier of this platform. - -By example, in the next picture, a Gephi installation was found in the `/opt/gephi-0.8-beta` directory. - -![addnetbeansplatform](/docs/Plugins/Build_a_plugin_without_Gephi_source_code/00_addnetbeansplatform.png) - -Click on the `Next` button, and change the platform name if required. In that example, it was required to change the platform name to "Gephi 0.8 beta", since the Gephi 0.8 alpha and beta have the same identifier, namely "Gephi 0.8 alpha". - -As you can see, two Gephi platforms have been registered. - -![addnetbeansplatformdone](/docs/Plugins/Build_a_plugin_without_Gephi_source_code/01_addnetbeansplatformdone.png) - -## Build a Plugin - -To build a plugin, it requires to: - -1. Create a module suite, event if your suite contains only one plugin, and make this suite use the Gephi platform; -2. Create a plugin in the module suite. -3. Add as dependencies of your modules the NetBeans and Gephi modules containing the functionalities required. - -### Creation of a Module Suite - -1. Click on "New|New Project"; - 1. In Categories, choose "NetBeans Modules, and "Module Suite" in projects, then click on the `Next` button; - 2. Configure the name, locations at your will. - 3. Choose the NetBeans Plaform you want to use. Here, you have to choose one of the Gephi platforms you have previously registered. - -### Creation of a Module - -1. Click on "New|New Project"; - 1. In Categories, choose "NetBeans Modules, and "Module" in projects, then click on the `Next` button; - 2. Configure the name, locations at your will. Add the new module to the module suite created in the previous step. - -![gephimoduleend](/docs/Plugins/Build_a_plugin_without_Gephi_source_code/02_gephimoduleend.png) - -*Display after the creation of the module suite and the module* - -### Add the Gephi Dependencies - -When some Gephi SPI/API are required by your module: - -1. In the Projects window, right-click on the "Libraries" item in the module tree.; -2. Select the "Add Module Dependency"; -3. In the Filter textfield, enter a part or the totality of the interface/class required by your module. -4. Select in the Module pane the module containing the interface/class required. - -## TroubleShootings - -### The Gephi SPI/API is not seen when editing and compiling - -If the interfaces and classes are not seen by the editor and the compiler, please process the following steps: - -1. Check the suite is using Gephi as its NetBeans platform by : - 1. Right-click on the suite project, click on the "Properties" item; - 2. In Categories, choose "Libraries". In the right pane, check whether the NetBeans Platform is using a Gephi installation, and change the platform if Gephi is not selected. - 3. In the Platform Modules tree, check the box for the gephi suite of modules, so that all the modules composing Gephi are used when compiling your module. - -### Module Version not compatible - -If an error message similar to "Cannot compile against a module: org-gephi-data-attributes-api.jar because of dependency: org.gephi.data.attributes.api > 0.8", it means the configuration of your module is requiring a Gephi module more recent than those provided by the Gephi platform used. A solution is to open the "Module Dependencies" dialog by doing: - -1. Right click on the module, choose the "Properties" item; -2. In Categories, click on "Libraries"; -3. In the "Module Dependencies" tab, select the module causing problem, and edit the requirements on its version number. diff --git a/docs/Plugins/Code_Sharing_Strategy.md b/docs/Plugins/Code_Sharing_Strategy.md deleted file mode 100644 index 359931d..0000000 --- a/docs/Plugins/Code_Sharing_Strategy.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -id: code_sharing_strategy -title: Code Sharing Strategy -sidebar_position: 16 ---- - -## Code sharing - -Some basic rules how we code in Gephi and how we use Netbeans: - -### Using libraries - -If you use libraries, wrap them into one or several modules. Further information here: http://wiki.netbeans.org/DevFaqWrapperModules - -The module codebase should be **org.gephi.lib.NAME**. - -Please send email to DEV mailing-list about that change and include it in the ChangeLog, not to forgot to update the [license page](http://gephi.org/developers/license/) on the website. - -### Code formatting - -Always format all the code you submit. Use the Netbeans format feature (right click > Format) with default parameters. - -### License - -This is the Gephi offical license. - - Copyright 2008-2012 Gephi - Authors : YOUR NAME - Website : http://www.gephi.org - - This file is part of Gephi. - - DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. - - Copyright 2012 Gephi Consortium. All rights reserved. - - The contents of this file are subject to the terms of either the GNU - General Public License Version 3 only ("GPL") or the Common - Development and Distribution License("CDDL") (collectively, the - "License"). You may not use this file except in compliance with the - License. You can obtain a copy of the License at - http://gephi.org/about/legal/license-notice/ - or /cddl-1.0.txt and /gpl-3.0.txt. See the License for the - specific language governing permissions and limitations under the - License. When distributing the software, include this License Header - Notice in each file and include the License files at - /cddl-1.0.txt and /gpl-3.0.txt. If applicable, add the following below the - License Header, with the fields enclosed by brackets [] replaced by - your own identifying information: - "Portions Copyrighted [year] [name of copyright owner]" - - If you wish your version of this file to be governed by only the CDDL - or only the GPL Version 3, indicate your decision by adding - "[Contributor] elects to include this software in this distribution - under the [CDDL or GPL Version 3] license." If you do not indicate a - single choice of license, a recipient has the option to distribute - your version of this file under either the CDDL, the GPL Version 3 or - to extend the choice of license to its licensees as provided above. - However, if you add GPL Version 3 code and therefore, elected the GPL - Version 3 license, then the option applies only if the new code is - made subject to such option by the copyright holder. - - Contributor(s): - - Portions Copyrighted 2011 Gephi Consortium. - -Please put your name on the top of the license at 'YOUR_NAME' and put this license in all files you own. - -You can directly include license texts in Netbeans using Tools>Templates. - -### Javadoc - -All open APIs (public interfaces) should have a complete Javadoc. This is important but commit to it only when you estimate a module is finished. -In the mean time, be sure your real name appears completely in all classes you own. This is the minimum thing you should add. As for license, it can be done with Netbeans. - -It is recommended to read the Javadoc [Good practices](http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html). It gives guidance and rules to make good Javadoc. - -### Module name convention - -Please respect new modules naming convention: -* No whitespace -* Add Wrapper in case of a library wrapper - -### Codebase convention - -New modules should follow the following codebase rules: - -| First Header | Second Header | -| ------------- | ------------- | -| API | org.gephi.NAME.api | -| API Implementation | org.gephi.NAME | -| SPI | org.gephi.NAME.spi | -| SPI Implementation | org.gephi.NAME.plugin | -| SPI Implementation UI | org.gephi.ui.NAME.plugin | -| Desktop UI | org.gephi.desktop.NAME | - - -### Module branding - -Branding options for Netbeans modules. Set it from module Properties > Display. - -* Display name can have whitespace -* Display Category: - * **Gephi Core** for all **API** and **Impl** modules - * **Plugin** for all **Plugin** and **PluginUI** modules - * **Libraries** for all libs - * **Gephi UI** for all **Desktop** modules - -And don't forget to set the license and author in the Build > Packaging settings. - -License should be **../gpl-3.0.txt** and Author **Gephi.org** - -## Distributed development - -### Get started - -Follow these links to get started with the development environment: -* [[Developer Handbook]] -* [Issues on Github](https://github.com/gephi/gephi/issues) - -### Git at Gephi - -There is a master branch on the Gephi repository which we call the trunk. This is the main branch where all the daily work happen. - -When we are releasing a major version we create a release branche (ex: 0.8) from master. These branches shouldn't get new features, only bug fixes. After the version is released, bugs that don't require to break compatibility of make significant changes (add/removed modules etc) should be developed in this branch and released as hot fixes. - -We like to always have the master branch working and developers should always make sure the code builds before commit. - -### Before commit - -'''Some simple steps to make sure it's done right:''' -* Run git status to see what's going on. -* Run git pull upstream BRANCH to get latest updates from GitHub. -* Run git add ... on the files you want to commit. If you removed some files run git rm .... This step is called 'staging' and add stuff to your commit. -* Run git status again. That lists the files you modified and are part of your next commit. -* Make sure you didn't forget any essential file. -* Run git commit -m "message" with a message with enough information for a fellow to understand. - -If you 'staged' something you didn't ant to stage run git reset FILES. If you want to reset a file changes run git checkout FILE. This will revert any changes you made to that files. - -'''Some things not to do:''' -* Don't add anything to the .gitignore file unless you've been told to. -* Don't commit changes in modules you are not working on. It happens that Netbeans will override some random xml or properties file. Don't commit those and revert them use 'git checkout'. -* If you encounter a conflict and you're not sure how to fix it, don't try random things. Ask we can help :-) - -Command line is fine for Git but you can also use [TortoiseGit](https://code.google.com/p/tortoisegit/) on Windows or [http://gitx.frim.nl/ GitX] if you're on Mac. A Netbeans Git module exists but is still in beta, so you should avoid using it. - -### Merging branches - -The master branch contains the trunk and all work happens there. When all developers work on separate modules it's relatively easy to manage and it's convenient to all work on the same code. However it gets complicated really fast when developers work on APIs, rewrite modules or refactor code. Therefore, for any significant work developers should create feature branches. This is typically the case for Google Summer of Code projects or large code changes. - -To create a new branch: -* Make sure you're on the master branch by running git branch -* Run git branch NAME to create the branch. Run git branch. Your new branch should appear. -* Run git checkout NAME to go to your branch -* Run git push origin NAME to push it to GitHub - -Features branches typically need to merge the master branch time to time to get up to date with core developments. To merge the master branch: -* Make sure you're on your feature branch by running git branch. If not, run git checkout BRANCH -* Run git pull upstream master. That will pull and merge the master branch. - -The merge will fail if some of the files Git want to merge have uncommited changes. IF that happens, commit your changes and in most cases Git will do the merge automatically. - -The master branch merges hotfixes in release branches when done. - -### Hot fixes - -Gephi is distributed through a installation package but also online as NBM packages. Thanks to Netbeans Platform, Gephi has the capability to update itself using the NBMs packages we store on our server. We call this the 'Update Center' and it is the same system we use to distribute third party plug-ins. It works like this. There is a XML files with all modules and version on our server and Gephi can read that files and compare online versions with it's local versions. If some modules have been updated the user is asked to update. - -This capability allows us to deploy hot fixes. When a bug is fixed and the version of the module is incremented the NBM file of the module is created and uploaded to our server. This is process is manual at the moment but it just takes a few minutes. We have done it many times to deliver bug fixes as soon as they are ready without waiting for a release. - -All bugs for hot fixes should be developed in release branches. For instance, if the latest stable release is 0.8 and we want to fix an issue and release it as hotfix the bug should be fixed in the 0.8 branch. The branch should be then merged to master to make sure the fix is in trunk as well. - -### Auto-Update - -Thanks to Netbeans Platform, Gephi has an auto-update feature. Update is done according to the "Specification version" for each module. Therefore, if you made a change that will be deployed through auto-update, increment the **Specification Version** of all modules you touched. diff --git a/docs/Plugins/GraphStreaming.md b/docs/Plugins/GraphStreaming.md deleted file mode 100644 index c39a8dd..0000000 --- a/docs/Plugins/GraphStreaming.md +++ /dev/null @@ -1,263 +0,0 @@ ---- -id: graphstreaming -title: GraphStreaming -sidebar_position: 17 ---- - -## Description - -The purpose of the Graph Streaming API is to build a unified framework for streaming graph objects. Gephi’s data structure and visualization engine has been built with the idea that a graph is not static and might change continuously. By connecting Gephi with external data-sources, we leverage its power to visualize and monitor complex systems or enterprise data in real-time. Moreover, the idea of streaming graph data goes beyond Gephi, and a unified and standardized API could bring interoperability with other available tools for graph and network analysis, as they could start to interoperate with other tools in a distributed and cooperative fashion. - -This plugin is also used to produce real-time analysis and visualization of graphs using Gephi. For more information on how to visualize Twitter data as graph objects using this plugin, see [[GraphStreaming#Other Examples|Other Examples]]. - -## Modules - -Gephi Graph Streaming is divided in different modules: The core modules, that defines the Graph Streaming API and its implementation, the Server modules, responsible for the HTTP REST Server, and the interface modules. - -### Graph Streaming API - -The Graph Streaming API is the core of this plugin. High-level modules can use this API in order to connect to external event sources. The API is format-agnostic, and the programmer must use an implemented StreamType for a given format, or implement one for a different format. For current supported formats, see [[GraphStreaming#Supported formats|Supported formats]]. - -You can use the Graph Streaming API to connect from the Toolkit, without a user interface. In order to connect to a stream data source, a component have to: - -1. Get the current Graph instance: -```java -ProjectController projectController = Lookup.getDefault().lookup(ProjectController.class); -Project project = projectController.getCurrentProject(); -Workspace workspace = projectController.getCurrentWorkspace(); - -// Get the graph instance -GraphController graphController = Lookup.getDefault().lookup(GraphController.class); -GraphModel graphModel = graphController.getModel(); -Graph graph = graphModel.getHierarchicalMixedGraph(); -``` -2. Get the StreamingController: -```java -StreamingController controller = Lookup.getDefault().lookup(StreamingController.class); -``` -3. Define the endpoint to connect to: -```java -// Connect to stream using the Streaming API -StreamingEndpoint endpoint = new StreamingEndpoint(); -// put the url of your master here -endpoint.setUrl(new URL("http://localhost:8080/workspace0")); -// endpoint.setStreamType() accepts a StreamType instance, so you -// have to get it using the controller -StreamType type = controller.getStreamType("JSON"); -endpoint.setStreamType(type); -``` -4. Connect to it and process: - -```java -StreamingConnection connection = controller.connect(endpoint, graph); -connection.asynchProcess(); // or connection.process() for synchronous processing -``` -The client will connect to the endpoint, process the events and update the graph accordingly. Note that the method connection.process() returns only when the stream finishes. If you want to asynchronously process the stream, you will want to call connection.asynchProcess(). But if you start the asynchronous processing of the stream, you lose control of when the stream finishes. In order to know when the stream finishes, you can control the StreamingConnection object to know when the connection was closed. If you want to know asynchronously when the connection was closed, without controlling the connection object, you can inform a listener to receive the event: -```java - StreamingConnection connection = controller.connect(endpoint, graph); - connection.addStatusListener(new StatusListener() { - public void onConnectionClosed(StreamingConnection connection) { - System.out.println("Connection was closed!"); - } - }); - connection.asynchProcess(); -``` -If you want to customize the behavior of event processing, doing something else than updating the graph, you can work with more low-level objects like StreamReaders. You can implement you own GraphEventHandler and pass it directly to the StreamReader implementation. For example, to count the received events you could do this: - -```java -final AtomicInteger counter = new AtomicInteger(); - -GraphEventHandler eventHandler = new GraphEventHandler() { - public void handleGraphEvent(GraphEvent event) { - counter.incrementAndGet(); - } -}; - -URL url = new URL("http://streamingserver/streamingcontext"); -url.openConnection(); -InputStream inputStream = url.openStream(); - -GraphEventBuilder eventBuilder = new GraphEventBuilder(endpoint.getUrl()); - -StreamReaderFactory readerFactory = Lookup.getDefault().lookup(StreamReaderFactory.class); -StreamReader reader = readerFactory.createStreamReader("JSON", eventHandler, eventBuilder); -streamReader.processStream(inputStream); -``` -The graph events will be sent to the GraphEventHandler as they arrive in the inputStream. The reported problems/exceptions during the streaming process are reported in the object Report: - -```java -Report report = connection.getReport(); -``` -You can also write the events in a given format using the StreamWriter: - -```java -ByteArrayOutputStream out = new ByteArrayOutputStream(); -StreamWriterFactory factory = Lookup.getDefault().lookup(StreamWriterFactory.class); -StreamWriter streamWriter = factory.createStreamWriter("JSON", out); -``` -Now you can use it as a GraphEventHandler instance (StreamWriter implements the GraphEventHandler interface), and you can write the events to the output using the given format: - -```java -StreamReaderFactory factory = Lookup.getDefault().lookup(StreamReaderFactory.class); -StreamReader reader = readerFactory.createStreamReader("JSON", streamWriter, eventBuilder); -streamReader.processStream(inputStream); -``` - -### Server Module - -The Server Module is implemented using Servlet standards. The servlets are run by an embedded [http://jetty.codehaus.org/jetty/ Jetty] instance. - -You can start a master programmatically using the API: - -``` -StreamingServer server = Lookup.getDefault().lookup(StreamingServer.class); -ServerControllerFactory controllerFactory = Lookup.getDefault().lookup(ServerControllerFactory.class); -ServerController serverController = controllerFactory.createServerController(graph); -String context = "/mycontext"; -server.register(serverController, context); -``` -Using this code, the Gephi master will be accessible in the following url: [http://your_ip_here:8080/mycontext http://your_ip_here:8080/mycontext] - -=== Plugin interface === -The modules responsible for the plugin interface use the core Graph Streaming API to connect to external streams, and the classes in the Server Module to start/stop the internal HTTP server. - - -== Supported formats == -The main Streaming API format supported by Gephi is JSON. For web-based systems, JSON is strongly encouraged over XML, as JSON is more compact and parsing is greatly simplified by the delimited parameter: every object is returned on its own line, and ends with a carriage return. In a streaming situation, it is more practical, as it is possible to parse the data as it arrives, without waiting for a closing tag or for the end of the stream. - -The current implementation of JSON Streaming Format is very simple and '''still subject to changes'''. It is composed of 6 types of events, divided in 2 types of elements (nodes and edges) and 3 types of operations (add, change, delete): - -* an: Add node -* cn: Change node -* dn: Delete node -* ae: Add edge> -* ce: Change edge -* de: Delete edge -Each event is composed by its event type and a list of objects of type node or edge, depending on the event type. Node and edge objects are similar, and composed of an identifier and a list of attributes. The "add edge" is the only operation in which there is three mandatory attributes: source, target and directed. Source and target are node identifiers, and directed is a boolean representing if the edge is directed or not. - -The events are currently represented in the JSON format as follows: - -```javascript -{ :{ :{ : , : }}} -``` -Following, we show a list of events with some examples for each type of event, represented in the current JSON format implementation: - -```javascript -{"an":{"A":{"label":"Streaming Node A","size":2}}} // add node A -{"an":{"B":{"label":"Streaming Node B","size":1}}} // add node B -{"an":{"C":{"label":"Streaming Node C","size":1}}} // add node C -{"ae":{"AB":{"source":"A","target":"B","directed":false,"weight":2}}} // add edge A->B -{"ae":{"BC":{"source":"B","target":"C","directed":false,"weight":1}}} // add edge B->C -{"ae":{"CA":{"source":"C","target":"A","directed":false,"weight":2}}} // add edge C->A -{"cn":{"C":{"size":2}}} // changes the size attribute to 2 -{"cn":{"B":{"label":null}}} // removes the label attribute -{"ce":{"AB":{"label":"From A to B"}}} // add the label attribute -{"de":{"BC":{}}} // delete edge BC -{"de":{"CA":{}}} // delete edge CA -{"dn":{"C":{}}} // delete node C -``` -With this format it is possible to put more than one object in each event, as in the following example: - -```javascript -{ "an" : { "A" : { "label" : "Streaming Node A" , "size" : 2 } , "B" : { "label" : "Streaming Node B" , "size" : 1 } , "C" : { "label" : "Streaming Node C" , "size" : 1 } } } -``` -But we recommend to send only one object in each event, as it is more suitable for a streaming approach: the data should be read as soon as possible by the client, and the approach using multiple objects by event slows the client reading, because it can't parse the JSON event object until a '\r' appears. - -'''We recall that this format is subject to changes, as more requirements are being added to the Graph Streaming API.''' - -'''Format changing considerations currently in progress''' - -There are some considerations in progress in order to adapt the JSON format to some requirements. - -The first one is to add support to '''filters'''. Filters are very important when changing groups of objects with the same characteristic. For example, if you want to change the color of all nodes with size=x, you could use a filter event. It would cost much less than sending one event for each node. - -Another requirement is to support '''identifiers to events'''. In some cases, it would be interesting to assign an identifier to the event. For example, in a distributed environment, the events are produced by event producers, but you cannot be sure that the event consumers receive the events in the same order. As a way to solve this problem, each event producer could assign a timestamp to the event, as a way to ensure that each event consumer produce the same results. - -Event identifiers will be assigned to events using a special "id" attribute, at the same level of the event type: - -```javascript -{ "id" : "1278944510" , "an" : { "A" : { "label" : "Streaming Node A" , "size" : 2 } } } -``` -This way, the event identifier will be parsed only if the "id" attribute is present in the event object. Someone that does not want to use identifiers should only ignore the "id" attribute: no overhead is added to the format, it remains compatible with "old style" events, and the format remains concise. - -== Source code == -The Gephi Graph Streaming is a Gephi Plugin supported by the core team, and the source code is available as a branch of the [https://github.com/gephi/gephi-plugins gephi-plugins repository]. In order to build the latest version, follow these steps: - -* Download and install the latest version of [http://netbeans.org/ Netbeans IDE]. -* Fork and checkout the latest version of the gephi-plugins repository: - -```bash -git clone git@github.com:username/gephi-plugins.git -``` -* Checkout the graph-streaming branch: -```bash -git checkout -t origin/graph-streaming -``` -* Start Netbeans and Open Project. This folder is automatically recognized as a module suite. -* Right click on the project and select 'Run'. This starts Gephi with the Graph Streaming plugin. - -## Examples -The Graph Streaming specification allow clients to interact with a master getting data and pushing data to it, in a REST architecture. The same data format used by the master to send graph events to the clients is used by clients to interact with the master. - -### Gephi as Master -In the first example, we will start Gephi as a master to provide graph information to its clients. At the Streaming Tab in the Gephi application, you can access all the features of graph streaming. You can start the Gephi Master by executing the following steps: - -* Run the Gephi application -* Create an empty workspace (File/New Project) -* Add some nodes and edges to your graph -* Go to the tab Streaming and right-click on the “Master Server” and select “Start” -By default, the HTTP server will listen at port 8080 in plain HTTP, and at port 8443 using SSL. The server path depends on your workspace: each workspace uses a different path. You can configure these parameters (and also Basic Authentication) at the “Settings…” button. - -By following these steps, an HTTP server is started, and it exposes a REST interface to access the workspace data by submitting events in the graph streaming format. - -Now, you can connect to Gephi using any HTTP client. For example, you can use [http://curl.haxx.se/ curl] to see the data flowing. First of all, open a shell prompt and execute the following command to get the complete graph, using the operation getGraph or no operation at all (getGraph is the default operation): - -```bash -curl "http://localhost:8080/workspace0?operation=getGraph" -``` -This operation connects to Gephi in streaming mode. You first receive the graph objects that are already in the graph. Every new object added to the graph is sent to the streaming client. For example, add some nodes to the graph in your workspace, and you will see the events appearing in the command line client. - -Other operations are used to retrieve node and edge data: - -```bash -curl "http://localhost:8080/workspace0?operation=getNode&id=A" -curl "http://localhost:8080/workspace0?operation=getEdge&id=AB" -``` -You can use the updateGraph operation to submit new events to your graph. For example, open another shell prompt and execute the following lines, one after the other: - -```bash -curl "http://localhost:8080/workspace0?operation=updateGraph" -d "{\"an\":{\"A\":{\"label\":\"Streaming Node A\"}}}" -curl "http://localhost:8080/workspace0?operation=updateGraph" -d "{\"an\":{\"B\":{\"label\":\"Streaming Node B\"}}}" -curl "http://localhost:8080/workspace0?operation=updateGraph" -d "{\"an\":{\"C\":{\"label\":\"Streaming Node C\"}}}" -curl "http://localhost:8080/workspace0?operation=updateGraph" -d "{\"ae\":{\"AB\":{\"source\":\"A\",\"target\":\"B\",\"directed\":false}}}" -curl "http://localhost:8080/workspace0?operation=updateGraph" -d "{\"ae\":{\"BC\":{\"source\":\"B\",\"target\":\"C\",\"directed\":false}}}" -curl "http://localhost:8080/workspace0?operation=updateGraph" -d "{\"ae\":{\"CA\":{\"source\":\"C\",\"target\":\"A\",\"directed\":false}}}" -``` -You should see the nodes and edges appearing in the workspace, until they form a triangle. At the same time, the events are sent to any client connected to the Master. You can send more events to the workspace using the same command line, just change the node and edge identifiers. - -The same events can be sent by just one HTTP request: - -```bash -curl "http://localhost:8080/workspace0?operation=updateGraph" -d $'{"an":{"A":{"label":"Streaming Node A"}}}\r -{"an":{"B":{"label":"Streaming Node B"}}}\r -{"an":{"C":{"label":"Streaming Node C"}}}\r -{"ae":{"AB":{"source":"A","target":"B","directed":false}}}\r -{"ae":{"BC":{"source":"B","target":"C","directed":false}}}\r -{"ae":{"CA":{"source":"C","target":"A","directed":false}}}' -``` -You are not limited to a single master by host: each Gephi workspace can be available as a master. - -### Gephi as Client -To illustrate how to connect to a master, [http://www.youtube.com/watch?v=7SW_FDiY0sg this video] shows Gephi connecting to a master and visualizing the received graph data in real time. The graph in this demo is a part of the Amazon.com library, where the nodes represent books and the edges represent their similarities. For each book, a node is added, the similar books are explored, adding the similar ones as nodes and the similarity as an edge. - -### Using a WebSocket Client - -'''This feature will be available in a near future.''' - -### Other Examples - -Some other examples are available by using a Python client. Source code and instructions are available in the [https://github.com/panisson/pygephi_graphstreaming pygephi_graphstreaming repository]. This repository also contains the source code of the Python server used to collect data from Twitter and create the video about the [https://gephi.org/2011/the-egyptian-revolution-on-twitter/ Egyptian Revolution on Twitter]. - -## Acknowledgements - -This plugin was implemented by [http://gephi.org/about/people/ André Panisson]. \ No newline at end of file diff --git a/docs/Plugins/Plugin_Quick_Start.md b/docs/Plugins/Plugin_Quick_Start.md deleted file mode 100644 index 95697c7..0000000 --- a/docs/Plugins/Plugin_Quick_Start.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -id: Plugin_Quick_Start -title: Plugin Quick Start -sidebar_position: 1 ---- - -**THIS PAGE IS OUTDATED, PLEASE CHECK THE README AT https://github.com/gephi/gephi-plugins** - -This HowTo covers how to get started with Gephi plugin development. Make sure you have [Git and GitHub](https://wiki.gephi.org/index.php/Install_Git_and_Set_Up_GitHub) set up before starting. - -## Checkout the gephi-plugins code - -We prepared an out of the box development environment on the gephi-plugins repository on GitHub. Once downloaded it doesn't need anything else to run a development version of Gephi. -Fork the project on GitHUb and clone the repository (replace username with your login): - -``git clone git@github.com:username/gephi-plugins.git`` - -Now you can open the project in [Netbeans](http://netbeans.org/). Gephi development happens in Netbeans because Gephi is based on the awesome [Netbeans Platform](http://platform.netbeans.org/). The gephi-plugins folder is automatically recognized when opening a project in Netbeans. Right click on the project and select **Run** to start Gephi. - -You can also run Gephi from the command-line using the `ant run` command. - -## Create a plugin - -1. In Netbeans, expand the **Gephi Plugins** project and right-click on Modules. Select **Add New...** -- Enter the plugin name: *MyFirstPlugin* and click **Next**. -- In the next panel, enter a unique codebase name, for instance *org.myname.myfirstplugin* and click **Finish**. -- In the Netbeans Project tree, you should see now your module *MyFirstPlugin*. Expand it to find its Source Package. Here you will place your code. - -![image](/docs/Plugins/Plugin_Quick_Start/00_image.png) -New module Step 1 - -![image](/docs/Plugins/Plugin_Quick_Start/01_image.png) -New module Step 2 - -![image](/docs/Plugins/Plugin_Quick_Start/02_image.png) -New module in the Projects tree - -You created a plugin, which doesn't do anything for the moment. When you build Gephi, your plugin is now fully integrated. It appears in the Plugin Center (Tools > Plugin). - -## Brand your plugin - -1. Right-click on your plugin project *MyFirstPlugin* and select **Properties**. -- Select **Display** on the left panel and fill **Display Category**, **Short Description** and **Long Description**. -- Select **Packaging** on the left panel and fill **License**, **Homepage** (if exists) and **Author** information. -- Click on OK to validate changes. - -![image](/docs/Plugins/Plugin_Quick_Start/03_image.png) -Branding Step 1 - -![image](/docs/Plugins/Plugin_Quick_Start/04_image.png) -Branding Step 2 - -## Distribute your plugin - -When you successfully tested your plugin, it's time to create a release. - -1. Right-click on the project and select **Package As** and then **NMBs**. -- Go to the **build** folder and find the created *plugin-release.zip* file. Individual NBM files (one per each module) are packaged in this zip. - -Now you can publish you plugin on the [Gephi Marketplace](https://marketplace.gephi.org). \ No newline at end of file diff --git a/docs/Plugins/Spigot_importer_with_Wizard.md b/docs/Plugins/Spigot_importer_with_Wizard.md deleted file mode 100644 index 34135c7..0000000 --- a/docs/Plugins/Spigot_importer_with_Wizard.md +++ /dev/null @@ -1,265 +0,0 @@ ---- -id: Spigot_importer_with_Wizard -title: Spigot importer with Wizard -sidebar_position: 6 ---- - -## Introduction - -This HowTo shows in about 20 minutes how to create a new spigot in Gephi. Spigots are like file importers, but with a different datasource. Spigots are the best way to import data from various data sources like Web Services, APIs, custom Databases or anything Java can read from. Like Importers, spigots push data to a `Container`, which hosts all data collected (i.e. nodes, edges and attributes). Moreover, spigots user interface supports **Wizards**, which makes it easy to have rich settings and a consistent flow. - -![spigot_menu](/docs/Plugins/Spigot_importer_with_Wizard/00_spigot_menu.png) - -*Import Spigot Menu* - -Please look at [[Plugin Quick Start]] to know how to create a new Netbeans Module. When you have your plugin module, that we will call `MySpigot`, you can start this tutorial. - -One can find spigot importer examples in the [Gephi source code](https://github.com/gephi/gephi/tree/master/modules/SpigotPlugin/). - -## Create a new Importer - -### Set Dependencies - -Add [[Import API]], [[LongTask API]], [[Utilities API]], [[Dialogs API]] and [[Lookup]] modules as dependencies for your plugin module MySpigot. See [[How To Set Module Dependencies]]. - -### Create SpigotImporterBuilder - -Importer Builder is a factory class for building the important instance, all Importers should have their own builder. - -Create a new builder class, for instance `MySpigotBuilder` that implements [SpigotImporterBuilder](https://gephi.org/docs/api/org/gephi/io/importer/spi/SpigotImporterBuilder.html). - -Leave the `buildImporter()` method empty for the moment and fill the `getName()` methods like below. - -```java -public String getName() { - return "My Spigot"; -} - -public SpigotImporter buildImporter() { - return null; -} -``` - -Add `@ServiceProvider` annotation to your builder class. Add the following line before `MySpigotBuilder` class definition, as shown below: - -```java -@ServiceProvider(service = SpigotImporterBuilder.class) -public class MySpigotBuilder implements SpigotImporterBuilder { -... -``` -### Create SpigotImporter - -The importer is where the job will be done. Create a new spigot importer class, for instance `MySpigot` that implements [SpigotImporter](http://gephi.org/docs/api/org/gephi/io/importer/spi/SpigotImporter.html). - -For more details, have a look at [ContainerLoader](http://gephi.org/docs/api/org/gephi/io/importer/api/ContainerLoader.html) and [Report](http://gephi.org/docs/api/org/gephi/io/importer/api/Report.html) documentation. - -Add also `LongTask` interface to your class, in order you will be able to use progress and cancel management. - -Your `MyImporter` would look like this: - -```java -public class MySpigot implements SpigotImporter, LongTask { - - private ContainerLoader container; - private Report report; - private ProgressTicket progressTicket; - private boolean cancel = false; - - public boolean execute(ContainerLoader loader) { - this.container = loader; - this.report = new Report(); - //Import done here - return !cancel; - } - - public ContainerLoader getContainer() { - return container; - } - - public Report getReport() { - return report; - } - - public boolean cancel() { - cancel = true; - return true; - } - - public void setProgressTicket(ProgressTicket progressTicket) { - this.progressTicket = progressTicket; - } -} -``` - -The infrastructure is set, the container for pushing data, the report for pushing logs and errors, and the progress management. - -Look at [File Importers examples](https://github.com/gephi/gephi/tree/master/modules/ImportPlugin) or [Spigots examples](https://github.com/gephi/gephi/tree/master/modules/SpigotPlugin/) code to learn how to push data to the container. - -### Finish the builder - -Go back to the `MySpigotBuilder` and complete `buildImporter()` method: - -```java -public SpigotImporter buildImporter() { - return new MySpigot(); -} -``` - -## Wizard UI - -You will create a `ImporterWizardUI` class for your importer and learn how to create a wizard to configure your MySpigot. - -A wizard is a set of panels, which follow each other with conditions. Consult the [Wizard API Javadoc](http://bits.netbeans.org/dev/javadoc/org-openide-dialogs/index.html?org/openide/WizardDescriptor.html). One can also find a more general tutorial on Netbeans Wizards [here](http://platform.netbeans.org/tutorials/nbm-wizard.html). The ImporterWizardUI class will provide the panels and the title of the spigot importer, as well as its description. But first, create a wizard panel. - -![spigot_howto1](/docs/Plugins/Spigot_importer_with_Wizard/01_spigot_howto1.png) - -*My Spigot* - -### Create Wizard Panel - -Create a new Java Panel class named `MySpigotWizardPanel1`. Go to File > New File > Swing GUI Forms > JPanel Form. - -Design your interface, by adding check boxes, text field etc. and go to the Source view. - -![spigot_howto_design](/docs/Plugins/Spigot_importer_with_Wizard/02_spigot_howto_design.png) - -Create an `unsetup()` method like below. This method will be called when the user leaves the wizard to actually configure your Spigot with the settings made in the UI. - -```java -public void unsetup(MySpigot importer) { - //Configure the importer - - //Example - //importer.setOption(optionCheckbox.isSelected()); -} -``` - -We will now edit this panel to implement the [WizardDescriptor.Panel](http://bits.netbeans.org/dev/javadoc/org-openide-dialogs/index.html?org/openide/WizardDescriptor.Panel.html) interface. - -See below how to implement this class - -```java -public class MySpigotWizardPanel1 extends javax.swing.JPanel implements WizardDescriptor.Panel { - - private List listeners; //these allow you to tell Gephi when UI changes are made - - - //Generated JPanel code goes here.... - - - public Component getComponent() { - return this; - } - - @Override - public String getName() { - return "Select Datasource"; //this will be the title of the panel in the wizard - } - - @Override - public HelpCtx getHelp() { - return HelpCtx.DEFAULT_HELP; - } - - /* - * You can use a settings object to keep track of state. Normally the - * settings object will be the WizardDescriptor, so you can use - * WizardDescriptor.getProperty & putProperty to store information entered - * by the user. - */ - public void readSettings(Object settings) { - } - - public void storeSettings(Object settings) { - } - - public boolean isValid() { - return true; //if you implement the change listeners properly, this should contain actual logic - } - - @Override - public void addChangeListener(ChangeListener cl) { - if (listeners == null) { - listeners = new ArrayList(); - } - - listeners.add(cl); - } - - @Override - public void removeChangeListener(ChangeListener cl) { - listeners.remove(cl); - } -} -``` - -### Create ImporterWizardUI - -Create a new spigot wizard UI class, for instance `MyImporterWizardUI` that implements [ImporterWizardUI](http://gephi.org/docs/api/org/gephi/io/importer/spi/ImporterWizardUI.html). - -This class is a singleton service, and registers your wizard in the system. It has two important methods: `setup()` and `unsetup`. The `unsetup()` method is called when the wizard is closed and is responsible for configuring the actual Spigot importer. In other words, the UI push settings values to the importer not the contrary. - -The sample below will help you: - -```java -public class MySpigotWizardUI implements ImporterWizardUI { - - private Panel[] panels = null; - - @Override - public String getDisplayName() { - return "My Spigot Importer"; - } - - @Override - public String getCategory() { - return "My Spigot"; - } - - @Override - public String getDescription() { - return "My Spigot imports very cool data"; - } - - @Override - public Panel[] getPanels() { - if (panels == null) { - panels = new Panel[1]; - panels[0] = new MySpigotWizardPanel1(); - } - return panels; - } - - @Override - public void setup(Panel panel) { - //Before opening the wizard - } - - @Override - public void unsetup(SpigotImporter importer, Panel panel) { - //When the wizard has been closed - ((MySpigotWizardPanel1) ((Panel) panels[0]).getComponent()).unsetup((MySpigot)importer); - - panels = null; - } - - @Override - public boolean isUIForImporter(Importer importer) { - return importer instanceof MySpigot; - } -} -``` - -Notice how the `unsetup()` method of `MySpigotWizardPanel1` is called. - -Ideally, this UI class is also responsible for saving the settings, in order to have the same settings the second time the spigot is used. For doing that, use the `setup()` method to load parameters in the panels. - -## Register the UI - -Add [[@ServiceProvider]] annotation to your UI class. Add the following line before `MySpigotWizardUI` class definition, as shown below: - -```java -@ServiceProvider(service = ImporterWizardUI.class) -public class MySpigotWizardUI implements ImporterWizardUI{ -... -``` \ No newline at end of file diff --git a/docs/Plugins/Update_a_plugin.md b/docs/Plugins/Update_a_plugin.md deleted file mode 100644 index 62febe9..0000000 --- a/docs/Plugins/Update_a_plugin.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -id: update-a-plugin -title: Update a plugin -sidebar_position: 15 ---- - -## Step1: New code - -A plugin usually use some of Gephi's APIs. For example for a layout plugin, it will depend on LayoutAPI and GraphAPI. Gephi developers sometimes have to change existing APIs, and break compatibility with existing plug-ins. In that case, plugin developers have to update their code to make it work with the new version. This is not likely to happen on APIs marked as **stable** on the [API Index](http://gephi.org/docs/api/). - -When an API is updated, a message is sent on the [gephi-plugins](http://gephi.org/mailman/listinfo/gephi-plugins) mailing-list and the **API Changes** section is updated on the API Index. - -## Step2: Update specification version - -The specification version is a version number given by the plugin developers in the module properties. Gephi uses specification versions to know when a plugin should be updated. For instance if a Gephi user has the plugin "SuperLayout" at version 1.1 and the 1.2 version is available on the website, Gephi will ask the user if he wants to update it. - -So, before uploading a new version of your plug-in, always increment the Specification Version. - -Right click on your plugin and select `Properties`. On the "API Versionning" tab increase the number of the specification version. - -## Step3: Upload on the Gephi Marketplace - -### Upload a new plugin - -1. Go to https://gephi.org/plugins/#/ -- Click on the **List your own > New plugin** menu item -- Log in -- Follow the instructions to upload the file. -- Wait for and admin approval. You will receive a notification by email when it is published. - -### Update an existing plugin - - -1. Go to https://gephi.org/plugins/#/ -- Log in -- Go to your user profile -- Select the plugin to update and follow instructions to upload a new version \ No newline at end of file diff --git a/docs/Plugins/index.md b/docs/Plugins/index.md deleted file mode 100644 index 3cdc6cb..0000000 --- a/docs/Plugins/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -id: index -title: Introduction -sidebar_position: 1 ---- - -This section is designed to help developers write [Gephi Plugins](https://gephi.org/plugins/#/). - -Gephi can be extended in many ways but the major categories are Layout, Export, Import, Data Laboratory, Filter, Generator, Metric, Preview, Tool, Appearance and Clustering. A good way to start is to look at examples with the [bootcamp](https://github.com/gephi/gephi-plugins-bootcamp). \ No newline at end of file diff --git a/docs/User_Manual/GUI.md b/docs/User_Manual/GUI.md deleted file mode 100644 index 497cf49..0000000 --- a/docs/User_Manual/GUI.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -id: gui -title: Graphical User Interface -sidebar_position: 3 -tags: - - GUI - - Startup ---- -## Global visual framework - -### Organization - -Gephi is a flexible desktop application and a visual framework: it does not constrain the user to do some tasks in a predefined way. On the contrary, the user is free to rearrange the environment, move panels, show/hide windows, etc. The GUI is set by default for three task families grouped as Overview, Data Laboratory and Preview. - -Modes are accessible under the main menu: -- **Overview**: graph manipulation mode. -- **Data Laboratory**: data visualization in tables. -- **Preview**: visual tuning before vectorial export. - -![image](/docs/User_Manual/GUI/00_image.png) - -![image](/docs/User_Manual/GUI/01_image.png) - -![image](/docs/User_Manual/GUI/02_image.png) - -### Workspaces - -A workspace is a whole environment for exploring one graph. If you want to analyze more graphs simultaneously, you need to create new workspaces. Create, delete and clean workspace data from the Edit menu. -Note that each new graph import creates a new workspace if you select the "Add full graph" option in the import window. Hence you are still able to work on the first graph later. - -![image](/docs/User_Manual/GUI/03_image.png) - -## Overview - -### Graph and Tools - -![image](/docs/User_Manual/GUI/04_image.png) -**Graph window** - Graph rendered on the center and tools on the sides. - -![image](/docs/User_Manual/GUI/05_image.png) -**Select** Highlight nodes under the cursor. - -![image](/docs/User_Manual/GUI/06_image.png) -**Edge selection color** Incoming links are colored differently than outgoing links. - -![image](/docs/User_Manual/GUI/07_image.png) -**Heatmap** Set color intensity on a node neighborhood, by the distance. - -![image](/docs/User_Manual/GUI/08_image.png) -**Multiple select** Nodes are selected under the rectangle. - -![image](/docs/User_Manual/GUI/09_image.png) -**Shorthest path** Display the shortest path if exist between two clicked nodes. - -### Layout - -Select an algorithm and set parameters on the fly. Save them into presets. - -![image](/docs/User_Manual/GUI/10_image.png) - -### Ranking - -Set numerical attributes to distribute node/edge colors, sizes, label colors and label sizes. Right-click on the window to display the ranked list of nodes or edges. - -![image](/docs/User_Manual/GUI/11_image.png) - -### Partition - -Node or edge grouping on attribute or computed metric. A color is assigned to each group, and can be changed by right-clicking on the window. - -![image](/docs/User_Manual/GUI/12_image.png) -Group List - -![image](/docs/User_Manual/GUI/13_image.png) -Pie chart - -### Statistics/metrics - -Run metrics and save reports in HTML. Node and edge computed results are available as attributes. - -![image](/docs/User_Manual/GUI/14_image.png) - -### Filters - -A library of filters is available to combine. Drag the filter (e.g., Degree Range) to build the query, and then set the parameters visually. Finally apply the query output to select elements or to filter them. When filtering is activated, changes appear in real time. - -![image](/docs/User_Manual/GUI/15_image.png) - -### Timeline - -Move left and right cursors to filter the graph on time intervals. - -![image](/docs/User_Manual/GUI/16_image.png) - -The timeline opens automatically when you open a dynamic network. Enable the timeline to set the time interval. Drag the bounds of the interval using your mouse. - -### Context - -Display the number of nodes and edges, the type of the graph and the percentage of visible nodes. - -![image](/docs/User_Manual/GUI/17_image.png) - -### Edit - -View and edit the attributes of a selected node. - -![image](/docs/User_Manual/GUI/18_image.png) - -## Data Laboratory - -Show node and edge attributes in a table, which also allows for dynamic regexp filtering. - -![image](/docs/User_Manual/GUI/19_image.png) - -## Preview - -### Settings - -Customizable visuals for vectorial export, which may be saved as presets. - -![image](/docs/User_Manual/GUI/20_image.png) - -### Visualization - -Fine tuning on nodes, edges and labels rendering. - -![image](/docs/User_Manual/GUI/21_image.png) \ No newline at end of file diff --git a/docs/User_Manual/Import_Dynamic_Data.md b/docs/User_Manual/Import_Dynamic_Data.md deleted file mode 100644 index b099abb..0000000 --- a/docs/User_Manual/Import_Dynamic_Data.md +++ /dev/null @@ -1,262 +0,0 @@ ---- -id: Import_Dynamic_Data -title: Import Dynamic Data -sidebar_position: 6 ---- - -Longitudinal (also called dynamic) networks are simply networks that evolve chronologically. If you imagine the network of your friends, the number of nodes, connections and attribute values grow and change as time passes. We call these dynamic attributes, because they have values associated with a particular moment. - -![intro-longitudinal](/docs/User_Manual/Import_Dynamic_Data/00_intro-longitudinal.png) - -*Longitudinal Networks* - -There are two ways to model a longitudinal network, either a collection of networks where each network is a particular point in time (a day, a month, ...) or a slice network where each element has an interval of existence. This can also be described as Discrete vs. Continuous representations of time. Gephi uses the latter, also known as **Intervals**, because it's more flexible. - -**For example:** - -Imagine a network of three nodes for the years 2007, 2008 and 2009. The years these nodes are present can be represented either as distinct points in time or as time intervals (as pictured on the left and right sides of the arrow below, respectively). - -![importdynamics-intervals](/docs/User_Manual/Import_Dynamic_Data/01_importdynamics-intervals.png) - -The second node, 'n2', is present during all three years and is represented by brackets enclosing the first and last years [2007, 2009]. Gephi automatically includes any dates, such as 2008, within this range. The first node, 'n1', however, is closed with a parenthesis rather than a bracket. This means the node was present in 2008 but **NOT** in 2009. - -Technically speaking, brackets are used for closed (also known as inclusive) intervals, while parentheses represent open intervals. In other words, dates enclosed within two brackets include both the startpoint and endpoint, whereas dates enclosed within two parentheses begins **after** the startpoint and ends **before** the endpoint. Half-closed intervals that incorporate both, like the [2007, 2009) example above, are also possible. - -Check the Data Laboratory to see how intervals are created for each node or edge. When the network is longitudinal, a Time Interval column is present that shows when the interval is present in the graph. You can visualize this by clicking the checkbox next to 'Time intervals as graphics' in the Configuration tab of the Data Laboratory. After enabling the timeline, be sure to adjust the size of the window of the sliding filter of your timeline, otherwise you will receive an error stating that Gephi "cannot animate timeline without an animation interval." - -## Import from GEXF File - -The [GEXF](http://gexf.net/format) format includes everything needed to represent longitudinal networks with intervals. You define a single network but add 'start' and 'end' attributes to set when a node/edge appears or vanish. - -### Basic example - -Below is our earlier example with three nodes from 2007 to 2009, but we've added edges to complete the example graph. - -```xml - - - - - - - - - - - - - - - -``` - -**Notice the following important points:** - -- We set **mode="dynamic"** to the **graph** element, that is needed, as GEXF can represent static graphs as well -- Use **start** and **end** for closed intervals (ex: [2007, 2009]) and **startopen** and **endopen** for open (ex: (2008, 2009)) -- Start and end dates for each element are optional. Leaving these empty will create an [-infinity, +infinity] interval. If only one bound is defined like for the second edge, it becomes [2009, +infinity]. - -The GEXF specifications, including dynamics, are available in the [GEXF Primer](http://gexf.net/format/primer.html). - -### Dynamic attributes - -The example above described how to represent the network topology over time, where nodes and edges are added or remove. Now let's see how to represent values changing over time, for example 'Price'. Below is the same network with a **price** attribute. The attribute definition in the ` `element is the same as it would be for a static GEXF, but the way that values are written has changed. - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -Keep in mind the following - -- To represent several values over time, the idea is to repeat the same **attvalue** for each period, with the same for but with different values and **start/end** -- It's not mandatory to set a value everywhere, in case of missing the default value is used -- For the node 'n2', the value '12' starts in 2008 and no end period is specified. That gives the interval [2008, +infinity] which means the value remains '12' in 2009 and after. - -The GEXF specifications, including dynamics attributes are available in the [GEXF Primer](https://gephi.org/gexf/format/primer.html). - -### Dynamic weight - -Normally an edge's weight is directly defined in the edge element with a particular value. Defining a dynamic **weight** attribute overrides this value and provides dynamic weight support. - -The rule is to define an edge attribute with the **weight** keyword for identifier. Then, use multiple 'attvalue' like explained above to set different values over time. - -```xml - - - -``` - - - -## Transform existing column in Time Interval - -Imagine a social network where each node represents a friend of yours and one of the attribute columns is the date you met. In order to transform this column into a dynamic interval take the following steps: - -- **Step 1:** Click on **Merge Columns** manipulator in the Data Laboratory. - -![transformlongitudinal-datalab1](/docs/User_Manual/Import_Dynamic_Data/02_transformlongitudinal-datalab1.png) - -- **Step 2:** From the available columns on the left, add the column or columns (if you have both a start and end period) you want to use to create the time interval. Then select **Create time interval** from the available merge strategies. - -![transformlongitudinal-datalab2](/docs/User_Manual/Import_Dynamic_Data/03_transformlongitudinal-datalab2.png) - -- **Step 3:** Select which column is the start and which is the end (or leave this blank if no end exists). If the column is numerical (integer, float, double), select **Parse numbers**. If the data are date strings, they can also be parsed and transformed into a time interval. Our 'First Met' column is just the day in the year, just a number. - -![transformlongitudinal-datalab3](/docs/User_Manual/Import_Dynamic_Data/04_transformlongitudinal-datalab3.png) - - -## Use Time Frame Import with several static files - -**NOTE: Outdated for Gephi 0.9.1, this documentation needs to be updated. Check https://github.com/gephi/gephi/issues/1546** - -This method can create a longitudinal network from a set of static "snaphsots" files. If you have a complete network at different point in time and want to see how both the network and its attributes changes over time this is the right method. - -Note that this method implementation is still experimental and may not work in all cases. Be sure to verify the following points: - -- Your node identifiers are **exactly** the same between the files. If not, at least the labels are (you can choose in the wizard). -- If GEXF, your network mode is set at **static** -- There is no previous graph in the workspace when you start importing Time Frame -- Attribute columns are the same in all files - -### Dataset - -We can take for instance three GEXF files and say each of this file is for a particular year, the network in 2007, in 2008 and in 2009. - -The **static** network in 2007, notice the price attribute: - -```xml - - - - - - - - - - - - - - - - - - - - - - - -``` - -The **static** network in 2008, the node '3' disappeared and a node '4' appears. Prices and edge's weight have changed also. - -```xml - - - - - - - - - - - - - - - - - - - - - - - - -``` - -The **static** network in 2009, the node '3' is back, the node '2' is gone and priced changed again. - -```xml - - - - - - - - - - - - - - - - - - - - - - -``` - -### Import in Gephi - -Do the following steps on a clear project to import your dataset: - -- **Step 1:** Import the first file and select **Time Frame** in the import report, click on OK. That will display a settings dialog. - -![importtimeframe1](/docs/User_Manual/Import_Dynamic_Data/05_importtimeframe1.png) - -- **Step 2:** Select either a Date or a real number as a time format. Real numbers is the default choice, here we put the year 2007. Click on OK, the file is imported. - -![importtimeframe2](/docs/User_Manual/Import_Dynamic_Data/06_importtimeframe2.png) - -- **Step 3:** You can now do the same for all other files, in a chronological order. For the second file select 2008, then 2009 etc. - -![importtimeframe3](/docs/User_Manual/Import_Dynamic_Data/07_importtimeframe3.png) - -The result is a longitudinal network in Gephi where nodes and edges have time intervals according how they were present in the different files. Similarly all attributes are dynamic attributes. The 'Price' attribute in the dataset in a **DYNAMIC_INTEGER** column and each value is associated with its interval. Moreover the edge's weight itself is dynamic. diff --git a/docs/User_Manual/Official_Videos/First_contact_with_gephi.md b/docs/User_Manual/Official_Videos/First_contact_with_gephi.md deleted file mode 100644 index 4bfce1d..0000000 --- a/docs/User_Manual/Official_Videos/First_contact_with_gephi.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -id: 01-first-contact-with-gephi -title: First contact with Gephi -sidebar_position: 1 -tags: - - Video ---- - - -# First contact with Gephi - - -https://www.youtube.com/watch?v=YM_37z_uURM \ No newline at end of file diff --git a/docs/User_Manual/Official_Videos/Layouts_clusters_and_where_to_find_them.md b/docs/User_Manual/Official_Videos/Layouts_clusters_and_where_to_find_them.md deleted file mode 100644 index 2f58416..0000000 --- a/docs/User_Manual/Official_Videos/Layouts_clusters_and_where_to_find_them.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -id: 02-layouts-clusters-and-where-to-find-them -title: Layouts, clusters, and where to find them -sidebar_position: 2 -tags: - - Video - - Layout - - Cluster ---- - - -# Layouts, clusters, and where to find them - - -https://www.youtube.com/watch?v=0LqY8OfSsKE&t=7s \ No newline at end of file diff --git a/docs/User_Manual/Official_Videos/_category_.json b/docs/User_Manual/Official_Videos/_category_.json deleted file mode 100644 index 4e065b7..0000000 --- a/docs/User_Manual/Official_Videos/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Official Video", - "position": 7 -} diff --git a/docs/User_Manual/Troubleshooting.md b/docs/User_Manual/Troubleshooting.md deleted file mode 100644 index 5a19592..0000000 --- a/docs/User_Manual/Troubleshooting.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -id: troubleshooting -title: Troubleshooting -sidebar_position: 1 -tags: - - Troubleshooting - - Startup ---- -## Memory issues - -Memory available to Gephi is determined by Java. Less or more memory can be allocated by configuring Gephi's startup settings. If too little memory is allocated, Gephi will stop running when it reached the limit and you will loose your current work. If too much memory is set, Java will not be able to start and return **JVM Creation failed** message. By default, maximum memory is set to 256mo or 512mo. - -To modify memory settings, you need to edit Gephi settings file. Modify the value after the `-Xmx` option to change the maximum heap space. For example, to use a heap size between 256 and 1024 MB, change the options to `-Xms256m` and `-Xmx1024m`. If you have Gephi open, you must close and reopen Gephi before new options take effect. On computers with 2GB of memory, you can set `-Xmx1400` to get maximum performance. - -### How to edit gephi.conf: - -- On **Windows**, go to the Gephi folder in Start menu and click on Startup Settings. Edit this file with Notepad or WordPad. Alternatively, go to `C:\Program Files\Gephi\etc\gephi.conf` and edit file manually. -- On **Mac OS X**, right-click on Gephi application icon and select Show Package Contents to open a new Finder window displaying a Contents folder. Open the Contents folder, and then open the `Resources/gephi/etc` folder, in which the gephi.conf file resides. Use TextEdit to edit the file. -- On **Linux**, go into your application directory and then into the `etc` folder. Edit the file with a text editor. - -**To use Gephi with more than ~1.5GB of memory, which could happen with very large graphs, you need to use A 64-bit version of Java. See following section.** - -### 64-bit - -Gephi has been successfully tested on 64-bit architecture (AMD64, Intel Core 2 Duo, Intel Core i7), 64 bits OS (Windows Vista 64-bit, Windows 7 64-bit) and 64-bit version of Java (JVM 64-Bit Server). To use more than ~1.5GB of memory in Gephi, which could happen with very large graphs, you need to have a 64-bit architecture, OS and a 64-bit JVM. A compatible 64-bit JRE or JDK can be downloaded from Java website. - -When multiple JRE or JDK are installed on the same machine, you can specify to Gephi to use a particular path. Edit `gephi.conf` as described in the upper section, uncomment the jdkhome line and set the JRE or JDK path. - -## Where are user files? - -Locate and delete gephi user directory to clean your installation. - -On Windows 2K/XP, user directory is located in - -`C:\Documents and Settings\username\Application Data\.gephi` - -On Windows Vista/Seven, user directory is located in - -`C:\Users\username\AppData\Roaming\.gephi` -(the logs files are under `C:\Users\username\AppData\Roaming\.gephi\{gephiVersion}\dev\var\log\messages.log` - -On Mac OS X, user directory is located in - -`/Users/username/Library/Application\ Support/gephi` - -On Linux, user directory is located in - -`/home/username/.gephi` - - - -## Linux issues - -### Select Sun JRE on Ubuntu - -After installing the Sun Java package, remember to run in command line: - -```sh -sudo update-alternatives --config java -sudo update-alternatives --config javac -``` - -In both cases select the option that has a path with java-6-sun in it. - -### Improve text rendering - -Add the following JVM parameter in the Gephi configuration file: - -``-J-Dawt.useSystemAAFontSettings=on`` - -Or add it to your environment variables: - -``export _JAVA_OPTIONS="-Dawt.useSystemAAFontSettings=on"`` - -## Mac OS X issues - -### Improve text rendering - -Add the following JVM parameter in the Gephi configuration file: - -``-J-Dapple.awt.graphics.UseQuartz=true`` - -## Windows issues - -### Gephi not using Graphical Card on Laptop - -*The troubleshooting explained is for Intel + Nvidia based laptop, note that the process is still relevant for AMD based laptop, just the tools involved might be different* - -If you have a laptop that has a dedicated graphical card (Nvidia), it's very probable that the laptop has also integrated card (Intel(R) UHD Graphics). - -Windows might probably, by default, wont' give Gephi the ability to use the dedicated graphical card, which will result in degraded performance for visualisation. - -To check that Gephi has or not get granted to use the correct graphical card : - -* Open Gephi -* On the top bar, go to **Tools -> Options**, a window will open -* On the tab go to **Visualisation** and then on the tab under **Open GL** - -![image](/docs/User_Manual/Troubleshooting/Graphical_Card_Information.png) - -On the right side of the windows, if you see something like `Nvidia Corporation` it means that Gephi is using the dedicated graphical card, all good. - -If you see something like `Intel UHD` it means Gephi is using the integrated graphical card. - - -To change this and force Windows to let Gephi use the dedicated graphical card : - -* Search for **Nvidia Control Panel** on your computer and open it. -* On left side, select **3D Settings -> Manage 3D settings** -* Then select the **Program settings** tab -* Click on **Add** and select **Gephi** -* Make sure the option **NVIDIA High Performance** is selected -* Click on **Apply** - -![image](/docs/User_Manual/Troubleshooting/Nvidia_3D_Panel.png) - -Then, restart Gephi. It should be now using the dedicated graphical card. \ No newline at end of file diff --git a/docs/User_Manual/index.md b/docs/User_Manual/index.md deleted file mode 100644 index d790023..0000000 --- a/docs/User_Manual/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -id: index -title: Introduction -sidebar_position: 1 -slug: / ---- - -Welcome to the official Gephi documentation resource. \ No newline at end of file diff --git a/docusaurus.common.ts b/docusaurus.common.ts new file mode 100644 index 0000000..39012c1 --- /dev/null +++ b/docusaurus.common.ts @@ -0,0 +1,116 @@ +import { themes } from "prism-react-renderer"; + +import type { Config } from "@docusaurus/types"; + +const lightCodeTheme = themes.github; +const darkCodeTheme = themes.dracula; + +const config: Config = { + title: "Gephi Documentation", + tagline: "The Open Graph Viz Platform", + url: "https://docs.gephi.org", + baseUrl: "/", + onBrokenLinks: "throw", + onBrokenMarkdownLinks: "warn", + favicon: "img/logo.svg", + + // GitHub pages deployment config. + // If you aren't using GitHub pages, you don't need these. + organizationName: "gephi", // Usually your GitHub org/user name. + projectName: "gephi", // Usually your repo name. + + // Even if you don't use internalization, you can use this field to set useful + // metadata like html lang. For example, if your site is Chinese, you may want + // to replace "en" with "zh-Hans". + i18n: { + defaultLocale: "en", + locales: ["en"], + }, + themeConfig: { + navbar: {}, + footer: { + style: "dark", + links: [ + { + title: "Project", + items: [ + { + label: "Gephi.org", + href: "https://gephi.org", + }, + { + label: "About", + href: "https://gephi.org/about", + }, + { + label: "FAQ", + href: "https://gephi.org/faq", + }, + { + label: "Documentation", + href: "https://docs.gephi.org", + }, + { + label: "Blog", + href: "https://gephi.wordpress.com/", + }, + { + label: "Donate", + href: "https://opencollective.com/gephi/donate?interval=oneTime&amount=5&name=&legalName=&email=", + }, + ], + }, + { + title: "Applications", + items: [ + { + label: "Gephi", + href: "https://gephi.org/desktop", + }, + { + label: "Gephi plugins", + href: "https://gephi.org/desktop/plugins", + }, + { + label: "Gephi Lite", + href: "https://gephi.org/lite", + }, + { + label: "Gephisto", + href: "https://jacomyma.github.io/gephisto", + }, + ], + }, + { + title: "Community", + items: [ + { + label: "Open Collective", + to: "https://opencollective.com/gephi", + }, + { + label: "GitHub", + to: "https://github.com/gephi", + }, + { + label: "Mastodon", + href: "https://vis.social/@Gephi", + }, + { + label: "Reddit", + href: "https://reddit.com/r/gephi", + }, + ], + }, + ], + copyright: `Copyright © ${new Date().getFullYear()} Gephi. Built with Docusaurus.`, + }, + prism: { + theme: lightCodeTheme, + darkTheme: darkCodeTheme, + additionalLanguages: ["java"], + }, + }, +}; + +export default config; diff --git a/docusaurus.config.js b/docusaurus.config.js deleted file mode 100644 index c3f528a..0000000 --- a/docusaurus.config.js +++ /dev/null @@ -1,127 +0,0 @@ -// @ts-check -// Note: type annotations allow type checking and IDEs autocompletion - -const lightCodeTheme = require('prism-react-renderer/themes/github'); -const darkCodeTheme = require('prism-react-renderer/themes/dracula'); - -/** @type {import('@docusaurus/types').Config} */ -const config = { - title: 'Gephi Documentation', - tagline: 'The Open Graph Viz Platform', - url: 'https://docs.gephi.org', - baseUrl: '/', - onBrokenLinks: 'throw', - onBrokenMarkdownLinks: 'warn', - favicon: 'img/favicon.ico', - - // GitHub pages deployment config. - // If you aren't using GitHub pages, you don't need these. - organizationName: 'gephi', // Usually your GitHub org/user name. - projectName: 'gephi', // Usually your repo name. - - // Even if you don't use internalization, you can use this field to set useful - // metadata like html lang. For example, if your site is Chinese, you may want - // to replace "en" with "zh-Hans". - i18n: { - defaultLocale: 'en', - locales: ['en'], - }, - - presets: [ - [ - '@docusaurus/preset-classic', - { - blog: false, - docs: { - routeBasePath: '/', - sidebarPath: require.resolve('./sidebars.js'), - // Please change this to your repo. - // Remove this to remove the "edit this page" links. - editUrl: - 'https://github.com/gephi/gephi-documentation/docs', - }, - theme: { - customCss: require.resolve('./src/css/custom.css'), - }, - }, - ], - ], - - themeConfig: - /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ - ({ - navbar: { - title: 'Gephi Documentation', - logo: { - alt: 'Gephi logo', - src: 'img/logo.svg', - }, - items: [ - { - to: '/', - activeBasePath: 'docs', - label: 'User Manual', - position: 'left', - }, - { - to: 'Developer_Documentation', - label: 'Developer Documentation', - position: 'left' - }, - { - to: 'Plugins', - label: 'Plugin Development', - position: 'left' - }, - { - href: 'https://github.com/gephi/gephi', - label: 'GitHub', - position: 'right', - }, - ], - }, - footer: { - style: 'dark', - links: [ - { - title: 'Community', - items: [ - { - label: 'Facebook', - href: 'https://www.facebook.com/groups/gephi', - }, - { - label: 'Twitter', - href: 'https://twitter.com/gephi', - }, - ], - }, - { - title: 'More', - items: [ - { - label: 'Official Website', - to: 'https://gephi.org/', - }, - { - label: 'Blog', - to: 'https://gephi.wordpress.com/', - }, - { - label: 'GitHub', - href: 'https://github.com/gephi/gephi', - }, - ], - }, - ], - copyright: `Copyright © ${new Date().getFullYear()} Gephi. Built with Docusaurus.`, - }, - prism: { - theme: lightCodeTheme, - darkTheme: darkCodeTheme, - additionalLanguages: ['java'], - }, - }), -}; - -module.exports = config; diff --git a/docs/Developer_Documentation/Code_Style.md b/gephi-desktop/docs/Developer_Documentation/Code_Style.md similarity index 100% rename from docs/Developer_Documentation/Code_Style.md rename to gephi-desktop/docs/Developer_Documentation/Code_Style.md diff --git a/docs/Developer_Documentation/How_to_build_Gephi.md b/gephi-desktop/docs/Developer_Documentation/How_to_build_Gephi.md similarity index 81% rename from docs/Developer_Documentation/How_to_build_Gephi.md rename to gephi-desktop/docs/Developer_Documentation/How_to_build_Gephi.md index c11fa20..8374d8a 100644 --- a/docs/Developer_Documentation/How_to_build_Gephi.md +++ b/gephi-desktop/docs/Developer_Documentation/How_to_build_Gephi.md @@ -10,16 +10,18 @@ Follow this guide to start developing the Gephi source code and test your change ### Netbeans Platform -The NetBeans Platform is a generic framework for Swing applications. It provides the "plumbing" that, before, every developer had to write themselves—saving state, connecting actions to menu items, toolbar items and keyboard shortcuts; window management, and so on. +The NetBeans Platform is a generic framework for Swing applications. It provides the "plumbing" and "windowing system" for large, modular Java Swing applications. The project is still maintained by the Apache Software Foundation. * [Description](https://netbeans.apache.org/kb/docs/platform/) * [Netbeans API Index](https://bits.netbeans.org/dev/javadoc/) -* [FAQ](https://netbeans.apache.org/wiki/DevFaqIndex.asciidoc) +* [FAQ](https://netbeans.apache.org/wiki/main/netbeansdevelopperfaq/DevFaqIndex/) + +Netbeans Platform dependencies are all available on Maven Central. It also depends on [FlatLaf](https://www.formdev.com/flatlaf/) for the look and feel. ### Gephi Architecture Gephi software architecture is modular and therefore each feature is split into modules. Modules depend on each other, and Gephi modules can either depend on other Gephi modules or Netbeans Platform modules. Plugins developers simply create new modules that contains their code, add dependencies to Gephi modules, and distribute their plugins by creating an NBM package. See Gephi APIs documentation to learn more about the API plugins that can be used by modules. -* [Gephi APIs documentation](http://gephi.org/docs/api) +* [Gephi APIs documentation](https://javadoc.io/doc/org.gephi/gephi/latest/index.html) ![image](/docs/Developer_Documentation/How-to-build-Gephi/00_image.png) @@ -27,8 +29,8 @@ Gephi software architecture is modular and therefore each feature is split into ### Requirements -* Java JDK 11 or later -* Apache Maven version 3.2.2 or later +* Java JDK 17 or later +* Apache Maven version 3.6.3 or later ### Checkout and Build the sources @@ -39,12 +41,18 @@ git clone https://github.com/gephi/gephi cd gephi ``` -Gephi uses Maven for building. Each module has its `POM.xml` file and there is a `gephi-parent` POM file that lists all the modules required to build. +Gephi uses Maven for building. Each module has its `pom.xml` file and there is a `gephi-parent` POM file that lists all the modules required to build. + +Run this command to build all modules. + +``` +mvn -T 4 clean install +``` -Run this command to build all modules. Note that this process could take some time. +By default, unit tests are turned off to speed up the build. To enable them, use: ``` -mvn clean install +mvn -T 4 package -P enableTests ``` ### Run it @@ -67,11 +75,11 @@ Once built, Gephi can be run from the `modules/application` folder using a speci ## Building Gephi in NetBeans -[Apache Netbeans](https://netbeans.apache.org/) is the default IDE to develop Gephi as it natively integrates with the Netbeans Platform. Loading the project is straightforward. +[Apache Netbeans](https://netbeans.apache.org/) is a great choice to develop Gephi as it natively integrates with the Netbeans Platform. Loading the project is straightforward. Open Netbeans and go to **File > Open Project** to look for the Gephi folder. Then, **Open Project**. Ensure the checkbox "Open Required Projects" is not selected. -![Opening Gephi](/docs/Developer_Documentation/How-to-build-Gephi/01_Opening Gephi.png) +![Opening Gephi](/docs/Developer_Documentation/How-to-build-Gephi/01_Opening_Gephi.png) Right-click on the project and select **Clean and Build**. @@ -93,19 +101,17 @@ When you make code changes in a module, make sure to **Clean and Build** this mo ## Building Gephi in IntelliJ IDEA -As Gephi is a Maven project it is well supported by IntelliJ but requires some tweaks to work properly. +As Gephi is a Maven project it is supported by IntelliJ but requires some tweaks to work properly. Open IntelliJ and open the Gephi folder. You'll be asked whether you want to Trust this Maven repository. Select **Trust Project**. -![Trust Maven](/docs/Developer_Documentation/How-to-build-Gephi/05_Trust Maven.png) - IntelliJ then takes some time to scan the project and resolve dependencies. Once completed, you should see Gephi properly listed as a project in the Project pane. -![Project loaded](/docs/Developer_Documentation/How-to-build-Gephi/06_Project loaded.png) +![Project loaded](/docs/Developer_Documentation/How-to-build-Gephi/06_Project_loaded.png) Then, navigate to IntelliJ's preferences panel **Build, Execution, Deployment > Build Tools > Maven > Runner** and select the option **Delegate IDE build/run actions to Maven**. This is a critical step. -![Maven delegate config](/docs/Developer_Documentation/How-to-build-Gephi/07_Maven delegate config.png) +![Maven delegate config](/docs/Developer_Documentation/How-to-build-Gephi/07_Maven_delegate_config.png) Next in the top-level menu select **Build > Build Project**. @@ -119,11 +125,11 @@ Once completed, create a run configuration by following **Run > Edit Configurati Here, select **Add new configuration** and search for **Maven**. -![Add Maven Config](/docs/Developer_Documentation/How-to-build-Gephi/10_Add Maven Config.png) +![Add Maven Config](/docs/Developer_Documentation/How-to-build-Gephi/10_Add_Maven_Config.png) Next, we'll configure two things here. Enter `nbm:cluster-app nbm:run-platform` into the **Command line** field and select the `modules/application` sub-directory into the **Working directory** chooser. Give Gephi as name for the configuration. -![Set Maven Config](/docs/Developer_Documentation/How-to-build-Gephi/11_Set Maven Config.png) +![Set Maven Config](/docs/Developer_Documentation/How-to-build-Gephi/11_Set_Maven_Config.png) Finally, you can run Gephi by selecting **Run > Run 'Gephi'** from the top-level menu. diff --git a/docs/Developer_Documentation/Localization.md b/gephi-desktop/docs/Developer_Documentation/Localization.md similarity index 100% rename from docs/Developer_Documentation/Localization.md rename to gephi-desktop/docs/Developer_Documentation/Localization.md diff --git a/gephi-desktop/docs/Developer_Documentation/Test_development_versions.md b/gephi-desktop/docs/Developer_Documentation/Test_development_versions.md new file mode 100644 index 0000000..6b76b97 --- /dev/null +++ b/gephi-desktop/docs/Developer_Documentation/Test_development_versions.md @@ -0,0 +1,13 @@ +--- +id: test_development_versions +title: Test Development Versions +sidebar_position: 6 +--- + +Development versions of Gephi can be installed and tested without affecting your stable Gephi installation. This is useful for trying out new features, before they are released in a stable version. It's also a way to benefit from bugfixes that are not yet available in the stable release. + +## Download Development Builds + +Development builds are located [here](https://github.com/gephi/gephi?tab=readme-ov-file#latest-releases). Download and install the version that matches your operating system. + +Note that development builds are not fully tested and may be unstable. They are provided for testing purposes only. Plugins also need to be installed manually (by downloading the NBM files from the plugin portal) as the automatic update center is not available in development builds. \ No newline at end of file diff --git a/docs/Developer_Documentation/_category_.json b/gephi-desktop/docs/Developer_Documentation/_category_.json similarity index 100% rename from docs/Developer_Documentation/_category_.json rename to gephi-desktop/docs/Developer_Documentation/_category_.json diff --git a/gephi-desktop/docs/Developer_Documentation/index.mdx b/gephi-desktop/docs/Developer_Documentation/index.mdx new file mode 100644 index 0000000..4fbd138 --- /dev/null +++ b/gephi-desktop/docs/Developer_Documentation/index.mdx @@ -0,0 +1,19 @@ +--- +id: index +title: Introduction +sidebar_position: 1 +--- + +Welcome, if you’re new to the codebase or want a fast, practical overview of Gephi’s architecture and how the project is organized, watch the short video and review the **[slides](https://gephi.wordpress.com/wp-content/uploads/2023/01/introduction-to-gephi-codebase-and-development.pdf)**. The video walks through Gephi’s core concepts, common workflows and the high‑level architecture (modules, APIs/SPIs, and extension points), + +Both resources are up‑to‑date and are an excellent first step. + +
+