We often hang out on this Telegram chat, which by the way is bridged to the IRC #docs:opensuse.org
and to #docs
on this Discord channel.
new document ------> review on structure and contents #1 ------> review on language, style and punctuation #1
|
|
marked "ready for release" <--- review on language #2 <--- review on contents #2 <------
...
Pipfile <<< project dependencies in pipenv format. That is what 'pipenv install' operates on.
requirements.txt <<< project dependencies in pip format. Added for compatibility.
pyproject.toml <<< project dependencies in poetry format. That is what 'poetry install' operates on.
project/ <<< 'cd' in here to run mkdocs commands (pipenv commands are to be run from the root directory)
docs/ <<< WHERE YOU CONTRIBUTE. You will be adding or editing files there.
mkdocs.yml <<< build config, but also used as Table of Contents. If you add a new file, reference it there.
...
...
.gitignore
should not let you commit any build
directory. Please make sure that is the case.
You can either install mkdocs from pip or from a virtual environment.
It's highly recommended to use a virtual environment manager and not pip
, so that the dependencies of this project won't mess with your system-wide python packages / modules. You still need to run pip once to install your favorite virtual environment manager.
We like using pipenv, which you install on openSUSE distributions with: pip3 install --user pipenv
. Then you'll need to add ~/.local/bin
to your PATH
. The best method for that depends on your shell:
* for bash
add PATH=$PATH:/home/your-user-name/.local/bin
to ~/.bashrc
; reload to apply changes with source ~/.bashrc
* for fish
run the following command once from a fish shell: set -Ua fish_user_paths /home/your-user-name/.local/bin
; start a fresh shell with exec fish
* for zsh
add export PATH=$PATH/home/your-user-name/.local/bin
to ~/.zshrc
; reload to apply changes with source ~/.zshrc
Install via poetry installer : curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
After installation command complete you will find your poetry install under $HOME/.poetry/bin
This directory will be automatically added to your $PATH environment variable, by appending a statement to your $HOME/.profile configuration (or equivalent files). If you do not feel comfortable with this, please pass the --no-modify-path flag to the installer and manually add the Poetry's bin directory to your path.
Another ways to install poetry are via openSUSE repository zypper install python38-poetry
for python 3.8 and zypper install python36-poetry
for python 3.6.
poetry
# Bash
poetry completions bash > /etc/bash_completion.d/poetry.bash-completion
# Bash (Homebrew)
poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-completion
# Fish
poetry completions fish > ~/.config/fish/completions/poetry.fish
# Fish (Homebrew)
poetry completions fish > (brew --prefix)/share/fish/vendor_completions.d/poetry.fish
# Zsh
poetry completions zsh > ~/.zfunc/_poetry
# Oh-My-Zsh
mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry
# prezto
poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry
cd
to it and run pipenv install
or poetry install
to install the dependencies, and then pipenv shell
or poetry shell
to run the environment. cd
to project
and run you mkdocs
commands from there.The only important command is mkdocs serve
; it generates the website from the source files and service it on http://127.0.0.1:8000/.
Use it now to make sure you can build and display the website.
Now you are read to work on the docs. You can either shut down the server with CTRL + c
or let it run. It will auto-reload and refresh your browser whenever you save your changes.
If you are new to git
and GitHub, read https://jarv.is/notes/how-to-pull-request-fork-github/.
When you are done working, go through the checklist before opening a Pull Request against our repository.
Checklist:
- [x] When doing git checkout -b <meaningful name> <...>
, did you make sure that meaningful name
satisfied the schema described under Branches below? If not, you can still rename it using git branch -m <new name that satsfies the schema>
.
- [x] Have you followed the style guidelines below under Style?
- [x] If you have added a new article:
- a) did it land in /project/docs
? If not, move it there.
- b) have you added it to table of contents? Just follow the examples already there. The urls look like https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/<some file.md>
- [x] Have you tested your work? If not consider the Clone, edit, test section above.
- [x] Are you going to make your PR editabled for us? If you don't know how, you will have to check the Allow edits from maintainers
checkbox on the Pull Request screen, in GitHub. Otherwise we won't be able to work with you on your PR.
main
or master
but dev
. I will merge from one milestone to the other.structure
(how the textual and multimedia contents breaks down into different parts)design
(web and non-web visuals)web-functions
(functionalities invoked from the web release of the docs)contents
(textual and multimedia contents)Structure. Each document should start with an intro stating the end goal, the important presuppositions (typically about pre-requirements) that the document is making, and an outline of the main steps on the path to the goal.
Technical jargon. Important and unavoidable jargon should be defined (typically inlined, with info boxes). Overall the document should be understanble by a teenager (think secondary school textbook).
Format: * reference points and path items in italics, ex: "Settings > Energy Saving" * action in bold, ex. "click Yes" * code instructions part of a stepwise recipe between line breaks in code, ex.
$ sudo zypper dup
sudo zypper dup
before anything else".