Sphinx to Confluence§
I am used to taking notes about almost everything I learned with Sphinx, now I can quickly share them with all my colleagues through Confluence. Main advantage about this method is that I can use it to share sensitive information without publishing static HTML website anywhere, which is public on both Github and Bitbucket (cloud versions).
TL;DR
Follow instructions described in this tutorial using parameters defined in Configuration
How am I doing this§
After a bit of research, I have encountered the combination of Git ⊕ Sphinx ⊕ ReestructuredText, the most suitable stack to take and publish notes.
ReestructuredText is used as a markup language for my notes because it is more affluent than Markdown.
Git tracks changes in .rst files (as they are plain text).
Sphinx automatically compiles notes and publishes .rst files to Confluence (check out this extension. Sphinx has additional extensions to enrich documentation functionalities, such as rendering Latex equations or building mermaid diagrams.
Configuration§
Set the following parameters up in the conf.py file (words between angle braces, e.g. <username>, must be provided by you):
The BASE URL of our company:
confluence_server_url = "https://<company domain>/wiki"(if using Atlassian Cloud).Your username:
confluence_server_user = "<username>@quant.global".Your password: You must create an API KEY as we log in with our Microsoft Account, then define it:
confluence_server_pass = os.getenv("<confluence_token_name>"). To create it, you have to follow these steps: - From Confluence, click your profile image on the top-right corner and then Profile. Under your public name, click on Manage your account. - On the Atlassian Account panel, click on Security on the sidebar, and then the third item: Create and manage your API Tokens. - On blue at the top, click on Create API Token, give it an ”easy to know for what it is” name and save it to your environment variables (or your usual method to remember these things).Your space key: Click from your Personal Space Overview click on Space Settings on the sidebar and then Manage Space > Space details and
confluence_space_key = <space_key_with_'~'_upfront>".Create the root page for your documentation, all pages included in the master ”toctree” will inherit from this page. Id can be found on page URL:
confluence_publish_root = <page_key>.
Workflow
I am using the following folders structure:
ConfluenceNotes ← This is the git repository
├───.gitignore ← Ignore all files that are outside source directories
├───topic-1 ← Organize your topics, run sphinx-quickstart here
│ ├───build ← Contents are automatically generated by Sphinx when compiling
│ │ ├───confluence
│ │ │ ├───topic-1
│ │ │ ├───math
│ │ │ └───_biblio
│ │ └───doctrees
│ │ └───topic-1
│ └───source ← Home of notes: conf.py and ``.rst`` files are here
│ ├───_biblio ← References ``.rst`` files to be used multiple times
│ ├───_downloads ← pdf and other files to be linked
│ ├───_images ← Images used in notes
│ ├───_static ← Used to add functionality to html compilation
│ ├───_templates ← Used to add functionality to html compilation
│ ├───conf.py ← Sphinx configuration explained above
│ └───*.rst ← Every ``.rst`` file is a different page
├───topic-2 ← Next topic. Link to different page in conf.py
│ └───...
└───...
It may sound much more convoluted than it is, as most of it is just managed by Sphinx and common to all Sphinx documentation projects.
When I start writing about a new topic, I just run:
mkdir <new_topic_folder> && cd !$
sphinx-quickstart
Answer the prompted questions and configure the Sphinx documentation in the source/conf.py file, which is almost always the same but points to different topic pages.
Warning
This is my current approach but it may change soon, there is a lot to be said about how sphinxcontrib-confluencebuilder manages root page and how it can help you have a clean and neat document hierarchy.
Writing§
When I feel like writing about any subtopic, I open the corresponding .rst file if already been created or if it is entirely brand new, I create a new file or even a new topic folder. To use math directives, I am using the Sphinx sphinx.ext.imgmath extension (the easiest way to make it work in Windows is by installing MikTeX), which renders equations to images and then inserts them in corresponding places.