Skip to content

maynor96/aimeos-docs

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Aimeos Documentation

Everyone is invited to improve the documentation! :-)

Just fork the repository, edit and add files, commit your changes and create a pull request:

Fork Aimeos docs

Read on, if you want to know, how to edit the documentation locally using Git and preview your changes on your local machine.

Setting up a git workflow

  • Create a free github account, if you do not already have one

  • Go to https://github.com/aimeos/aimeos-docs and fork the repo (click on the "Fork" button on the top right, see image above)

  • In your terminal, clone the forked repo to a destination of your choice with:

    > git clone https://github.com/[YOUR-GITHUB-ACCOUNT]/aimeos-docs.git

    This creates a folder called aimeos-docs.

  • Change into your newly created local aimeos-docs folder and add upstream links to be able to always keep your local clone up-to-date:

    > cd aimeos-doc
    > git remote add upstream git://github.com/aimeos/aimeos-docs.git

    You can verify your git configuration using git remote -v:

    > git remote -v
    
    origin https://github.com/<YOUR_GITHUB_REPO>/aimeos-docs.git (fetch)
    origin https://github.com/<YOUR_GITHUB_REPO>/aimeos-docs.git (push)
    upstream git://github.com/aimeos/aimeos-docs.git (fetch)
    upstream git://github.com/aimeos/aimeos-docs.git (push)

    Keep your local clone and your fork up-to-date with:

    > git fetch upstream
    > git merge upstream/master master
    > git push

    Optional:

    > git rebase upstream/master
  • For each change you would like to commit, create and checkout a new branch, e.g.:

    > git checkout -b <name-of-your-current-commit-branch>
  • Edit the mardown files you wish to contribute to, add a comment and push them to your fork:

    > git add <the-file-you-just-edited>.md
    > git commit -m '<describe briefly, what you changed>'
    > git push -u origin <name-of-your-current-commit-branch>
  • Go to your aimeos-docs fork in your github account and create a pull request.

  • Once your are finished with your commit, don't forget to switch back to the master branch in your local clone:

    > git checkout master
  • Once your commit is merged, you can delete your local and remote branches again with:

    > git branch --delete <branch_name>
    > git push origin --delete <branch_name>

    Then update your local clone and your github fork again with:

    > git fetch upstream
    > git merge upstream/master master
    > git push

Build and live reload your local clone (optional)

Contributing to aimeos-docs does not require anything else but editing the markdown files. However, if you would like to run a local version of the generated docs, you need Python 3. This enables the local generation of the complete aimeos-docs as well as running a local development server that reloads automatically as soon as changes to the repository files are detected.

Install Python 3

Please refer to sources on the internet for explanations on how to install Python 3 on your operating system. One such resource would be Real Python: Installing Python.

Install mkdocs and required dependencies

aimeos-docs uses mkdocs to create static html files from markdown files. Install mkdocs and the dependencies required by aimeos-docs with pip:

pip install mkdocs mkdocs-material

Start the local server

Run mkdocs serve to start a local server on http://127.0.0.1:8000. Now, whenever you make changes to any file, the server will automatically reload and display your edited version.

Build the docs

To build the aimeos-docs locally, use mkdocs build. You can now open the documentation in your browser from the newly generated <your-aimeos-docs-clone-folder>/docs´s index.html.

Troubleshooting

Due to some configuration limits, mkdocs serve will tell you that it couldn't find versions.js. Also, mkdocs serve as well as mkdocs build might warn about an unknown analytics configuration attribute. You can safely ignore these warnings.

About

Aimeos documentation

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • HTML 46.5%
  • CSS 44.4%
  • Python 9.1%